URL Shortener API

POST /api/shorten

Create a short URL. Requires a creatorId (UUID) so links can be listed and deleted later.

Content-Type: application/json

{
  "url": "https://example.com/long-path",
  "creatorId": "your-uuid-v4",
  "customCode": "my-brand",
  "expiresIn": 24,
  "password": "optional-unlock-secret"
}

Examples

# cURL
curl -X POST https://urlshort.at/api/shorten \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","creatorId":"550e8400-e29b-41d4-a716-446655440000"}'

// JavaScript (fetch)
const res = await fetch("https://urlshort.at/api/shorten", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://example.com",
    creatorId: crypto.randomUUID(),
  }),
});
const data = await res.json();

# Python (requests)
import requests, uuid
r = requests.post("https://urlshort.at/api/shorten", json={
    "url": "https://example.com",
    "creatorId": str(uuid.uuid4()),
})
print(r.json())

expiresIn is optional hours until expiry. customCode is optional (3–32 chars, alphanumeric, _ -). password is optional — visitors unlock before redirect. Response includes manageToken, manageUrl, and publicStatsUrl (shown once; bookmark the manage URL).

GET / PATCH /api/manage/:code

Token-gated edit without an account. Pass token as a query param (GET) or JSON body field (PATCH). PATCH may update destination, expiresIn, isActive, and password (null to clear).

GET /api/urls

Query: creatorId, optional page, limit.

GET /api/stats/:code

Query: creatorId (must match link owner).

DELETE /api/urls/:code

Query: creatorId.

Public tools

• GET /api/public/summary/:code — click count + destination (no auth)
• GET /api/public/stats/:code — shareable click snapshot + 14-day series (powers /s/:code)
• GET /api/public/resolve?url= — expand a urlshort.at link
• POST /api/public/bulk-shorten — body { urls: string[], creatorId } (max 50)
• POST /api/bio · GET /api/bio/:slug · PATCH /api/bio/:slug — link-in-bio pages