API Documentation

REST API v1.1.0

Base URL:

Overview

The URL Shortener API provides programmatic access to create and manage short URLs. All responses are in JSON format unless the request is made from a console client.

Authentication

No authentication required for public endpoints

Rate Limiting

3 requests per 10 seconds for URL creation

Endpoints

POST /url

Create short URL

Create a new shortened URL with an optional custom slug.

Request Body

Parameter	Type	Required	Description
url	string	Required	The URL to shorten
slug	string	Optional	Custom slug for the short URL

Example Request

curl -X POST /url \
  -H "Content-Type: application/json" \
  -d '{"url":"https://github.com/casjay/csj.lol","slug":"github"}'

const response = await fetch('/url', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://github.com/casjay/csj.lol',
    slug: 'github'
  })
});

const data = await response.json();

import requests

response = requests.post(
    '/url',
    json={
        'url': 'https://github.com/casjay/csj.lol',
        'slug': 'github'
    }
)

data = response.json()

Responses

200 OK Success

{
  "_id": "507f1f77bcf86cd799439011",
  "url": "https://github.com/casjay/csj.lol",
  "slug": "github",
  "clicks": 0,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "shortUrl": "/github"
}

429 Rate Limit Exceeded

{
  "error": "Too many requests, please try again later."
}

500 Server Error

{
  "message": "Error description",
  "stack": "Stack trace (development mode only)"
}

GET /api/urls

List all URLs

Get a paginated list of all shortened URLs.

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	50	Items per page (max 100)
sort	string	newest	Sort order: "newest" or "oldest"

Example Request

curl "/api/urls?page=1&limit=10&sort=newest"

Response

200 OK

{
  "urls": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "url": "https://github.com/casjay/csj.lol",
      "slug": "github",
      "clicks": 42,
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalPages": 5,
    "totalUrls": 50,
    "hasNext": true,
    "hasPrev": false
  }
}

GET /:slug

Redirect to original URL

Redirect to the original URL and increment the click counter.

Path Parameters

Parameter	Type	Description
slug	string	The short URL slug

Example

/github
→ Redirects to → https://github.com/casjay/csj.lol

Responses

302 Found Redirects to original URL

404 Not Found Short URL not found

Console Client Support

The API automatically detects console clients (curl, wget, httpie) and returns plain text responses.

$ curl -X POST /url \
    -H "Content-Type: application/json" \
    -d '{"url":"https://github.com"}'

/abc12

Reverse Proxy Support

Full support for reverse proxy deployments with automatic hostname detection.

X-Forwarded-Host - Original hostname

X-Forwarded-Proto - Original protocol

X-Forwarded-For - Client IP address

Host - Fallback hostname

HTTP Status Codes

200 Success

302 Redirect

400 Bad Request

404 Not Found

429 Rate Limited

500 Server Error