NanoLink API Docs

Endpoints

Authentication Required

To protect the deep analytics data, certain administrative routes are locked down. You must pass a Bearer token in the headers of your HTTP request to access them.

Authorization: Bearer hackclub-pi-zero

Reviewers: Copy and paste the dynamically generated cURL commands below to test the endpoints instantly!

POST /api/shorten 30 REQ / MIN

Converts a long URL into a short code. Protected by custom rate-limiting middleware and strict Zod payload validation. Supports Vanity URLs and strict Self-Destruct limits.

cURL Request Example

Response Example (201 Created)

{
  "success": true,
  "message": "Link shortened successfully!",
  "code": "hack",
  "shortUrl": "http://localhost:3000/hack",
  "originalUrl": "https://hackclub.com"
}

Optional Features (JSON Body)

customCode: Pass a custom string to create a Vanity URL instead of a random hash.
maxClicks: Burn-after-reading. Link self-destructs after X clicks.
expiresAt: Strict Time-to-Live (TTL). Pass an ISO-8601 date to auto-delete the link at a specific time.

GET /:code

Instantly redirects to the target destination. Silently parses the User-Agent header to log deep demographics (OS, Device, Browser). Fires asynchronous Discord Webhooks on every click and enforces self-destruct logic.

cURL Request Example

Response Example (301 Moved Permanently)

HTTP/1.1 301 Moved Permanently
Location: https://hackclub.com

Response Example (410 Gone - If Self-Destruct Triggered)

HTTP/1.1 410 Gone
"This link has reached its maximum view count and self-destructed."

GET /api/qr/:code

Dynamically generates a scannable, high-res PNG of a QR code pointing to your short link. Uses in-memory Node Buffers parsed into native Web Standard Uint8Arrays for instant streaming.

cURL Request Example

Response Example (200 OK)

HTTP/1.1 200 OK
Content-Type: image/png

[Raw Binary Image Data]

GET /api/stats/:code AUTH REQUIRED

Retrieves live click analytics. Uses a relational SQLite query to join the link details with an array of individual click events, showcasing the parsed OS, Device, and Browser data for every single click.

cURL Request Example

Response Example (200 OK)

{
  "success": true,
  "data": {
    "id": "hack",
    "originalUrl": "https://hackclub.com",
    "clicks": 1,
    "createdAt": "2026-05-09T10:11:35.433Z",
    "lastClicked": "2026-05-09T10:22:17.541Z",
    "recentActivity": [
      {
        "id": 1,
        "os": "Mac OS",
        "browser": "Chrome",
        "device": "Desktop",
        "timestamp": "2026-05-09T10:22:17.541Z"
      }
    ]
  }
}

GET /api/links AUTH REQUIRED

Returns a paginated JSON array of all active short codes stored in the database. Protected against memory-overflows on massive datasets via query-based Cursor Pagination (?page=1&limit=10).

cURL Request Example

Response Example (200 OK)

{
  "success": true,
  "meta": {
    "totalItems": 15,
    "totalPages": 2,
    "currentPage": 1,
    "itemsPerPage": 10
  },
  "data": [
    {
      "id": "hack",
      "originalUrl": "https://hackclub.com",
      "clicks": 42,
      "createdAt": "2026-05-08T09:00:00Z",
      "expiresAt": "2026-06-08T09:00:00Z"
    }
  ]
}