Skip to main content

​
Introduction

The shrtnr API is a RESTful API built with Next.js App Router that allows you to create, manage, and track shortened URLs. The API uses JSON for request and response payloads and leverages NextAuth for session-based authentication.

​
Base URL

All API endpoints are relative to your shrtnr instance: 
https://your-domain.com/api
For local development: 
http://localhost:3000/api

​
API Endpoints

Create Short Link

Generate a new shortened URL with optional custom slug

List Links

Retrieve all links created by the authenticated user

Update Link

Modify an existing link’s short code or expiration

Delete Link

Permanently remove a shortened link

​
Endpoint Reference

​
POST /api/shorten

Create a new shortened link. Anonymous users can create links with auto-generated codes, while authenticated users can use custom slugs. Request Body: 
{
  "url": "https://example.com/very/long/url",
  "customSlug": "my-link",
  "expiresInDays": 14
}
Parameters:
  • url (required): The original URL to shorten. Must be a valid HTTP/HTTPS URL.
  • customSlug (optional): Custom short code (1-20 chars: letters, numbers, _, -). Requires authentication.
  • expiresInDays (optional): Link expiration in days (1-30). Default: 7 days.
Response: 
{
  "shortCode": "my-link",
  "shortUrl": "https://your-domain.com/my-link"
}
Custom slugs require authentication. Anonymous users receive auto-generated 8-character codes.
Retrieve all links created by the authenticated user, ordered by creation date (newest first). Authentication: Required Response: 
[
  {
    "id": 123,
    "short_code": "my-link",
    "original_url": "https://example.com/very/long/url",
    "created_at": "2026-03-01T10:30:00.000Z",
    "expires_at": "2026-03-15T10:30:00.000Z",
    "custom_slug": true,
    "clicks": 42,
    "user_id": "abc123xyz"
  }
]
Response Fields:
  • id: Unique numeric identifier
  • short_code: The short code used in the URL
  • original_url: The destination URL
  • created_at: ISO 8601 timestamp of creation
  • expires_at: ISO 8601 expiration timestamp (or null for no expiration)
  • custom_slug: Boolean indicating if this was a custom slug
  • clicks: Total number of times this link was accessed
  • user_id: ID of the user who created the link

​
PATCH /api/links/[id]

Update an existing link’s short code or expiration date. Only the link owner can update their links. Authentication: Required Request Body: 
{
  "shortCode": "new-slug",
  "expiresAt": "2026-04-01T00:00:00.000Z"
}
Parameters:
  • shortCode (optional): New short code (must follow slug rules: 1-20 chars, alphanumeric, _, -)
  • expiresAt (optional): New expiration date as ISO 8601 string, or null to remove expiration
Response: 
{
  "ok": true
}
Changing the short code will invalidate the old URL and clear the Redis cache.

​
DELETE /api/links/[id]

Permanently delete a shortened link. Only the link owner can delete their links. Authentication: Required Response: 
{
  "ok": true
}

​
Error Responses

All endpoints return consistent error responses: 
{
  "error": "Error message describing what went wrong"
}
Common HTTP Status Codes:
  • 400 Bad Request: Invalid input (malformed URL, invalid slug, etc.)
  • 401 Unauthorized: Authentication required or session expired
  • 404 Not Found: Link not found or you don’t have permission
  • 500 Internal Server Error: Server-side error occurred
  • 503 Service Unavailable: Database not initialized
Example Error Responses: 
{
  "error": "Invalid URL"
}

​
Rate Limiting

Currently, shrtnr does not implement rate limiting at the API level. Consider implementing this based on your infrastructure needs (e.g., using Next.js middleware or a reverse proxy).

​
Data Persistence

Shrtnr uses a dual-storage approach:
  • PostgreSQL: Persistent storage for all link data, user accounts, and analytics
  • Redis: High-speed cache for URL resolution and improved performance
When links are created or updated, Redis cache entries are automatically managed with TTL matching the link expiration.

​
Next Steps

Authentication

Learn how to authenticate API requests

Shorten Endpoint

Create short links via API

Build docs developers (and LLMs) love

Get started for freeTalk to us