URL Shortener API Documentation

All requests require an API key for authorization. The API key must be included in the x-api-key header for each request.

Authorization

API Key: The x-api-key header must be included with every request to authenticate the client. Requests without this header will return a 401 Unauthorized error.

Example:

x-api-key: YOUR_API_KEY

1. Shorten URL

POST /url/shorten

Shortens a long URL and optionally allows specifying a custom alias.

Headers
  • x-api-key (required): API key for authorization.
Request Body
Field Type Required Description
longUrlstringYesThe long URL to shorten (must be a valid URI).
customAliasstringNoCustom alias for the shortened URL. Must match pattern ^[a-zA-Z0-9_-]{1,50}$.
Sample Request
{
    "longUrl": "https://example.com/very/long/url",
    "customAlias": "myAlias123"
}
Sample Response

200 OK

{
    "shortUrl": "https://short.ly/myAlias123",
    "longUrl": "https://example.com/very/long/url",
    "shortCode": "myAlias123"
}
Error Responses

400 Bad Request

{
    "message": "Invalid input data",
    "errors": ["longUrl must be a valid URI"]
}

500 Internal Server Error

{
    "message": "An unexpected error occurred"
}

2. Expand URL

GET /url/expand/:shortCode

Expands a shortened URL and redirects to the original long URL.

Path Parameters
Field Type Required Description
shortCodestringYesThe short code or custom alias for the shortened URL.
Sample Request
GET /url/expand/myAlias123
Response

Redirect 301

Redirects the client to the original long URL.

Error Responses

404 Not Found

{
    "message": "Short code not found"
}

500 Internal Server Error

{
    "message": "An unexpected error occurred"
}

URL Expiry

All shortened URLs have a default expiry of 90 days unless configured otherwise.

After the expiry period, the short code will no longer be valid, and any requests to expand the URL will result in a 404 Not Found error.