Skip to main content
GET
/
{url_code}
URL Redirect
curl --request GET \
  --url https://api.example.com/{url_code}
{
  "RedirectResponse": {}
}
Redirect to the destination URL associated with a short URL code. This is the core functionality that makes short URLs work - when users visit the short URL, they are automatically redirected to the target destination.

​
Path Parameters

​
url_code
string
required
The short URL code to redirect. Supports sub-paths that will be appended to the destination URL.Examples:
  • /my-link → redirects to destination URL
  • /my-link/page/123 → redirects to destination URL + /page/123

​
Redirect Behavior

The endpoint performs the following steps:
  1. Parse URL Code: If the path contains /, splits at the first / to extract the code and sub-path
  2. Lookup URL: Finds the URL mapping in the database
  3. Check State: For password-protected URLs, verifies the URL is not paused
  4. Update Hits: Increments the hit counter in the background (for password-protected URLs only)
  5. Redirect: Returns a 302 redirect to the destination URL (with sub-path appended if present)
Hit Tracking: Only password-protected URLs have their hits tracked. Unprotected URLs redirect without updating statistics.

​
Sub-Path Support

The redirect endpoint supports appending sub-paths to the destination URL:

​
Response

​
RedirectResponse
HTTP 302
The endpoint returns an HTTP 302 redirect response with the Location header set to the destination URL.

​
Status Codes

  • 302 Found - Successful redirect to destination URL
  • 404 Not Found - Short URL code doesn’t exist
  • 423 Locked - URL is temporarily paused (only for password-protected URLs)

​
Request Examples

curl -L https://surl.example.com/my-link

​
Response Examples

HTTP/1.1 302 Found
Location: https://example.com/very/long/url
Content-Length: 0

​
Background Hit Counter

For password-protected URLs, the hit counter is updated asynchronously:
  • Uses FastAPI’s BackgroundTasks to avoid blocking the redirect
  • Increments url_hits field in the URLStats collection by 1
  • Runs after the redirect response is sent to the client
  • Does not affect redirect performance
Paused URLs: When a password-protected URL is paused (via the /pause endpoint), attempting to access it will return a 423 Locked error instead of redirecting. Use /resume to reactivate the URL.

​
URL State Check

The redirect only checks the url_state for password-protected URLs: 
if len(entry["url_pass"]) > 0:  # Password-protected
    stats = await app.URLStats.find_one({"url_code": url_code})
    if not stats["url_state"]:
        raise HTTPException(status_code=423, detail="Redirect temporarily paused")
    else:
        background_tasks.add_task(update_hits_sync, url_code)
Unprotected URLs (without passwords) always redirect immediately without state checks.

​
Performance Notes

  • Database lookup uses indexed url_code field for fast retrieval
  • Sub-path parsing uses simple string operations
  • Hit tracking happens asynchronously to maintain redirect speed
  • Typical redirect latency: less than 50ms (excluding database query time)

Build docs developers (and LLMs) love

Get started for freeTalk to us