POST /api/shorten
Create a new short link. Anonymous users can create random short codes, while authenticated users can use custom slugs.
Authentication
Optional for basic usage. Required for custom slugs. Use session-based authentication.
Request Body
The original URL to shorten. Must be a valid HTTP or HTTPS URL.
- Required field (cannot be empty or whitespace-only)
- Must be a valid URL with
http:// or https:// protocol
- Trimmed before validation
Custom short code for the URL. Only available to authenticated users.
- Requires authentication (401 if not signed in)
- Must match regex:
/^[a-zA-Z0-9_-]{1,20}$/
- Allowed characters: letters (a-z, A-Z), numbers (0-9), underscore (_), hyphen (-)
- Length: 1-20 characters
- Must be unique (not already in use)
Number of days until the link expires.
- Default: 7 days
- Minimum: 1 day
- Maximum: 30 days
- Values outside range are clamped automatically
- Non-numeric values default to 7 days
Response
The generated or custom short code (8 characters if auto-generated).
The complete short URL ready to share.
Error Responses
Error message describing what went wrong.
400 Bad Request
"URL is required" - Missing or empty URL"Invalid URL" - URL is not a valid HTTP/HTTPS URL"Invalid slug: use letters, numbers, _ and - only (1–20 chars)" - Custom slug doesn’t match validation rules"Slug already in use" - Custom slug is already taken
401 Unauthorized
"Sign in to use a custom slug" - Attempted to use custom slug without authentication
500 Internal Server Error
"Something went wrong" - Unexpected server error
Examples
curl -X POST https://shrtnr.app/api/shorten \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/very/long/url/path"
}'
Success Response
{
"shortCode": "Xy9pQz1m",
"shortUrl": "https://shrtnr.app/Xy9pQz1m"
}
Error Response
{
"error": "Invalid URL"
}
{
"error": "Sign in to use a custom slug"
}
Auto-generated short codes use nanoid with 8 characters, providing URL-safe random strings. Custom slugs are case-sensitive. MyLink and mylink are treated as different slugs.