Skip to main content

​
Endpoint

This endpoint resolves a secure link using its short code. It validates access conditions (expiration, view limits, password) and either redirects to the target URL or returns file content.
GET /l/{shortCode}

​
Path Parameters

​
shortCode
string
required
The unique 8-character identifier for the secure link.Format: Alphanumeric string (case-sensitive)Example: K2x9pLmN

​
Headers

​
X-Link-Password
string
Password required to access password-protected links.When Required:
  • Only needed if the link was created with a password
  • Returns 401 Unauthorized if missing or incorrect
Example: mySecurePassword123
​
Accept
string
Controls response format for redirect links.Behavior:
  • application/json: Returns JSON with redirect URL (status 200)
  • Any other value or not set: Returns HTTP 302 redirect
Note: Only applies to REDIRECT type links, not file downloadsExample: application/json
​
User-Agent
string
Client user agent string (automatically sent by browsers).Purpose:
  • Captured for audit logging
  • Helps track access patterns and detect suspicious activity
Example: Mozilla/5.0 (Windows NT 10.0; Win64; x64)...

​
Response Types

For REDIRECT type links without Accept: application/json header:
​
Status
302 Found
Client is redirected to the target URL.
​
Location
header
Contains the target URL for redirection.Example: https://example.com/document.pdf
For REDIRECT type links with Accept: application/json header:
​
type
string
Always “REDIRECT” for redirect links.
​
targetUrl
string
The destination URL.Example: https://example.com/document.pdf

​
File Download

For DOWNLOAD type links (created via file upload):
​
Status
200 OK
File content is returned in the response body.
​
Content-Disposition
header
Specifies the original filename for download.Format: attachment; filename="original-name.pdf"Example: attachment; filename="report-2024.xlsx"
​
Content-Type
header
Set to application/octet-stream for binary file downloads.
​
Body
binary
Raw file content as a resource stream.

​
Status Codes

​
200
OK
For JSON requests: Successfully resolved redirect link, JSON response returned.For file downloads: File content returned successfully.
​
302
Found
For redirect links: Client is being redirected to the target URL.Access tracking: This access is recorded as successful in audit logs.
​
401
Unauthorized
Password authentication failed. Possible causes:PASSWORD_REQUIRED:
  • Link requires a password but X-Link-Password header was not provided
  • Error message: “Password required”
INVALID_PASSWORD:
  • Password provided in X-Link-Password header is incorrect
  • Error message: “Invalid password”
Access tracking: Failed access attempts are recorded with the specific failure reason.
​
404
Not Found
Link does not exist or file is missing. Possible causes:NOT_FOUND (link):
  • No link exists with the provided short code
  • Error message: “Link not found”
NOT_FOUND (file):
  • Link exists but the associated file has been deleted from storage
  • Error message: “File not found”
Access tracking: Recorded as NOT_FOUND in audit logs.
​
410
Gone
Link has been invalidated. Possible causes:REVOKED:
  • Link was manually revoked via DELETE /l/
  • Error message: “Link has been revoked”
VIEW_LIMIT_REACHED:
  • Link has reached its maximum view count
  • Link is automatically marked as revoked
  • Error message: “Link has reached its view limit”
EXPIRED:
  • Current time is past the link’s expiration timestamp
  • Error message: “Link has expired”
Access tracking: Failed access attempts are recorded with the specific failure reason.
​
500
Internal Server Error
Unexpected server error occurred.Error response includes:
  • timestamp: When the error occurred
  • status: HTTP status code (500)
  • error: “Internal Server Error”
  • message: Generic error message with reference ID
  • path: Request path that caused the error

​
Validation & Security Checks

The endpoint performs the following checks in order:
  1. Link Existence: Verify link with short code exists (404 if not)
  2. Revocation Status: Check if link has been manually revoked (410 if revoked)
  3. Password Validation: If password is set, validate header (401 if missing/wrong)
  4. View Limit: Check if maxViews exceeded (410 if limit reached, auto-revokes)
  5. Expiration: Check if current time > expiresAt (410 if expired)
  6. File Existence (downloads only): Verify file exists on disk (404 if missing)
  7. Increment View Counter: Increment current view count for successful access
  8. Audit Logging: Record access attempt with result, IP, user agent

​
Examples

curl -i http://localhost:8080/l/K2x9pLmN
Response (302 Found) - Browser Redirect: 
HTTP/1.1 302 Found
Location: https://example.com
Response (200 OK) - JSON: 
{
  "type": "REDIRECT",
  "targetUrl": "https://example.com"
}

curl -i http://localhost:8080/l/P9qRsTuV \
  -H "X-Link-Password: SecurePass2024!"
Response (302 Found): 
HTTP/1.1 302 Found
Location: https://example.com/confidential-document.pdf

​
Download File

curl -O -J http://localhost:8080/l/F5gH7jKl
Response (200 OK): 
HTTP/1.1 200 OK
Content-Disposition: attachment; filename="document.pdf"
Content-Type: application/octet-stream
Content-Length: 245681

<binary file content>
Request: 
curl -i http://localhost:8080/l/invalid123
Response (404 Not Found): 
{
  "timestamp": "2026-03-04T14:30:00+00:00",
  "status": 404,
  "error": "Not Found",
  "message": "Link not found",
  "path": "/l/invalid123"
}

​
Error: Password Required

Request (missing password header): 
curl -i http://localhost:8080/l/P9qRsTuV
Response (401 Unauthorized): 
{
  "timestamp": "2026-03-04T14:30:00+00:00",
  "status": 401,
  "error": "Unauthorized",
  "message": "Password required",
  "path": "/l/P9qRsTuV"
}

​
Error: Invalid Password

Request (wrong password): 
curl -i http://localhost:8080/l/P9qRsTuV \
  -H "X-Link-Password: WrongPassword"
Response (401 Unauthorized): 
{
  "timestamp": "2026-03-04T14:30:00+00:00",
  "status": 401,
  "error": "Unauthorized",
  "message": "Invalid password",
  "path": "/l/P9qRsTuV"
}
Request: 
curl -i http://localhost:8080/l/revokedLink
Response (410 Gone): 
{
  "timestamp": "2026-03-04T14:30:00+00:00",
  "status": 410,
  "error": "Gone",
  "message": "Link has been revoked",
  "path": "/l/revokedLink"
}

​
Error: View Limit Reached

Request (link has reached max views): 
curl -i http://localhost:8080/l/limitReached
Response (410 Gone): 
{
  "timestamp": "2026-03-04T14:30:00+00:00",
  "status": 410,
  "error": "Gone",
  "message": "Link has reached its view limit",
  "path": "/l/limitReached"
}
When a link reaches its view limit, it is automatically marked as revoked to prevent further access attempts.
Request (current time past expiresAt): 
curl -i http://localhost:8080/l/expiredLink
Response (410 Gone): 
{
  "timestamp": "2026-03-04T14:30:00+00:00",
  "status": 410,
  "error": "Gone",
  "message": "Link has expired",
  "path": "/l/expiredLink"
}

​
Access Tracking

Every access attempt (successful or failed) is recorded in the audit log with:
  • Short Code: Link identifier
  • Access Result: SUCCESS, NOT_FOUND, REVOKED, PASSWORD_REQUIRED, INVALID_PASSWORD, VIEW_LIMIT_REACHED, EXPIRED
  • IP Address: Client IP address (from HttpServletRequest.getRemoteAddr())
  • User Agent: Client user agent string
  • Timestamp: When the access occurred
You can retrieve access statistics via the Statistics API.

​
Important Notes

View Counter: Successful accesses increment the view count. Once maxViews is reached, the link is automatically revoked and returns 410 Gone for subsequent requests.
Password Security: Passwords are validated using bcrypt comparison. The plaintext password in the X-Link-Password header is never stored or logged.
IP & User Agent Tracking: All access attempts capture client IP and user agent for security auditing and analytics purposes.

Create Link

Create a new secure redirect link

Upload Link

Upload a file and create a download link

Revoke Link

Manually revoke a secure link

Access Statistics

View access patterns and metrics

Build docs developers (and LLMs) love

Get started for freeTalk to us