Skip to main content

​
Overview

Secure Link API allows you to create shortened, trackable links for any external URL. This guide walks you through creating links with various configuration options. To create a basic link without expiration or view limits:
1

Prepare the request

Create a POST request to /api/links with the target URL:
curl -X POST http://localhost:8080/api/links \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://example.com/destination"
  }'
2

Receive the response

The API returns a 201 Created response with the link details:
{
  "shortCode": "abc123",
  "accessUrl": "http://localhost:8080/l/abc123",
  "expiresAt": null,
  "maxViews": null
}
The shortCode is a unique identifier generated for each link. Save this value if you need to revoke the link later.
3

Share the link

Use the accessUrl to share with your users. When accessed, it will redirect to the target URL.

​
Request Parameters

The CreateLinkRequestDto accepts the following parameters:
ParameterTypeRequiredValidationDescription
targetUrlstringYesMust be a valid URLThe destination URL to redirect to
expiresAtstring (ISO 8601)NoMust be a future date/timeWhen the link should expire
maxViewsintegerNoMust be positiveMaximum number of times the link can be accessed
passwordstringNo-Optional password protection (see Password Protection)

​
Advanced Examples

Set an expiration date using ISO 8601 format with timezone offset: 
curl -X POST http://localhost:8080/api/links \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://example.com/limited-offer",
    "expiresAt": "2026-12-31T23:59:59+00:00"
  }'
The expiresAt value must be in the future. Past dates will be rejected with a validation error.
Limit how many times a link can be accessed: 
curl -X POST http://localhost:8080/api/links \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://example.com/exclusive",
    "maxViews": 100
  }'

​
Combining Multiple Options

You can combine expiration, view limits, and password protection: 
curl -X POST http://localhost:8080/api/links \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://example.com/secure-content",
    "expiresAt": "2026-06-30T23:59:59+00:00",
    "maxViews": 50,
    "password": "secret123"
  }'

​
Error Handling

​
Validation Errors

If validation fails, you’ll receive a 400 Bad Request response: 
{
  "timestamp": "2026-03-04T14:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "targetUrl: must be a valid URL",
  "path": "/api/links"
}
Common validation errors:
  • targetUrl: must not be blank - The targetUrl field is required
  • targetUrl: must be a valid URL - The URL format is invalid
  • expiresAt: must be a future date - The expiration date is in the past
  • maxViews: must be greater than 0 - The maxViews must be a positive number

​
Server Errors

For unexpected errors, you’ll receive a 500 Internal Server Error with a reference ID: 
{
  "timestamp": "2026-03-04T14:30:00Z",
  "status": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Reference ID: 550e8400-e29b-41d4-a716-446655440000",
  "path": "/api/links"
}
Use the Reference ID when reporting issues to support for faster troubleshooting.

​
Best Practices

Always validate that your target URLs are properly formatted and accessible before creating links. This prevents user confusion when links fail to resolve.
Set expiration times based on your use case:
  • Marketing campaigns: Match the campaign end date
  • Temporary shares: 24-48 hours
  • Long-term redirects: Consider no expiration
If you need to revoke links later, store the shortCode value securely in your database with appropriate access controls.
For links with maxViews set, monitor access patterns to detect if the limit is too restrictive or too permissive.

​
Next Steps

Upload Files

Learn how to create download links for uploaded files

Password Protection

Secure your links with password protection

Link Expiration

Configure expiration and time-to-live settings

Revocation

Manually revoke links before expiration

Build docs developers (and LLMs) love

Get started for freeTalk to us