Skip to main content

​
Endpoint

This endpoint creates a new secure link that redirects to a target URL with optional expiration, view limits, and password protection.
POST /api/links

​
Request Body

​
targetUrl
string
required
The destination URL that the secure link will redirect to.Validation:
  • Required field (cannot be blank)
  • Must be a valid URL format
  • Must include protocol (http:// or https://)
Example: https://example.com/document.pdf
​
expiresAt
string
ISO 8601 timestamp indicating when the link should expire.Validation:
  • Must be a future date/time
  • Format: YYYY-MM-DDTHH:mm:ss±HH:mm (ISO 8601 with timezone)
  • If not provided, the link will not have time-based expiration
Example: 2026-12-31T23:59:59+00:00
​
maxViews
integer
Maximum number of times the link can be accessed before it becomes invalid.Validation:
  • Must be a positive integer (> 0)
  • If not provided, the link will not have view-based expiration
Example: 5
​
password
string
Optional password required to access the link. When set, clients must provide this password via the X-Link-Password header when accessing the link.Security:
  • Stored as a bcrypt hash
  • Required via HTTP header on link resolution
  • No length restrictions (recommended: 8+ characters)
Example: mySecurePassword123

​
Response

​
shortCode
string
Unique identifier for the created link. This code is used in the access URL.Format: 8-character alphanumeric stringExample: K2x9pLmN
​
accessUrl
string
The full URL path to access the secure link.Format: /l/{shortCode}Example: http://localhost:8080/l/K2x9pLmN
​
expiresAt
string
ISO 8601 timestamp when the link expires (if expiration was set).Format: YYYY-MM-DDTHH:mm:ss±HH:mmExample: 2026-12-31T23:59:59+00:00
​
maxViews
integer
Maximum number of views allowed (if view limit was set).Example: 5

​
Status Codes

​
201
Created
Link successfully created. Response body contains the link details.
​
400
Bad Request
Request validation failed. Possible causes:
  • Missing or blank targetUrl
  • Invalid URL format in targetUrl
  • expiresAt is not a future date
  • maxViews is not a positive integer
Error response includes:
  • timestamp: When the error occurred
  • status: HTTP status code (400)
  • error: “Bad Request”
  • message: Specific validation error (e.g., “targetUrl: must be a well-formed URL”)
  • path: Request path that caused the error
​
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 for troubleshooting
  • path: Request path that caused the error

​
Examples

curl -X POST http://localhost:8080/api/links \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://example.com"
  }'
Response (201 Created): 
{
  "shortCode": "K2x9pLmN",
  "accessUrl": "http://localhost:8080/l/K2x9pLmN",
  "expiresAt": null,
  "maxViews": null
}

curl -X POST http://localhost:8080/api/links \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://example.com/report.pdf",
    "expiresAt": "2026-12-31T23:59:59+00:00"
  }'
Response (201 Created): 
{
  "shortCode": "A7bCdEfG",
  "accessUrl": "http://localhost:8080/l/A7bCdEfG",
  "expiresAt": "2026-12-31T23:59:59+00:00",
  "maxViews": null
}

curl -X POST http://localhost:8080/api/links \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://example.com/secret-video",
    "maxViews": 10
  }'
Response (201 Created): 
{
  "shortCode": "X1yZ2aBc",
  "accessUrl": "http://localhost:8080/l/X1yZ2aBc",
  "expiresAt": null,
  "maxViews": 10
}

curl -X POST http://localhost:8080/api/links \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://example.com/confidential-document.pdf",
    "expiresAt": "2026-03-15T18:00:00+00:00",
    "maxViews": 5,
    "password": "SecurePass2024!"
  }'
Response (201 Created): 
{
  "shortCode": "P9qRsTuV",
  "accessUrl": "http://localhost:8080/l/P9qRsTuV",
  "expiresAt": "2026-03-15T18:00:00+00:00",
  "maxViews": 5
}
Password is not returned in the response for security reasons. Users must provide the password via the X-Link-Password header when accessing the link.

​
Validation Error Example

Request with invalid URL: 
curl -X POST http://localhost:8080/api/links \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "not-a-valid-url",
    "maxViews": 5
  }'
Response (400 Bad Request): 
{
  "timestamp": "2026-03-04T14:30:00+00:00",
  "status": 400,
  "error": "Bad Request",
  "message": "targetUrl: must be a valid URL",
  "path": "/api/links"
}

​
Past Expiration Date Error

Request with past date: 
curl -X POST http://localhost:8080/api/links \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://example.com",
    "expiresAt": "2020-01-01T00:00:00+00:00"
  }'
Response (400 Bad Request): 
{
  "timestamp": "2026-03-04T14:30:00+00:00",
  "status": 400,
  "error": "Bad Request",
  "message": "expiresAt: must be a future date",
  "path": "/api/links"
}

Upload Link

Upload a file and create a secure download link

Resolve Link

Access a secure link using its short code

Revoke Link

Permanently disable a secure link

Build docs developers (and LLMs) love

Get started for freeTalk to us