API Documentation
Integrate Whisprly's powerful URL shortening into your applications
Getting Started
The Whisprly API provides programmatic access to create and manage short links. All API endpoints are RESTful and return JSON responses.
Base URL: https://your-domain.com/api
Content-Type: application/json
Authentication
Currently, the API is open for public use with rate limiting. Authentication will be added in future versions.
Rate Limit: 50 requests per 15 minutes
Endpoints
POST
/api/links/shorten
Create a new short link
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
url |
string | Yes | The long URL to shorten |
customAlias |
string | No | Custom alias for the short link (3-50 chars) |
expiresIn |
number | No | Hours until link expires (1-8760) |
password |
string | No | Password to protect the link |
category |
string | No | Category for organization |
Example Request
curl -X POST https://your-domain.com/api/links/shorten \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/very-long-url",
"customAlias": "my-link",
"expiresIn": 24,
"category": "marketing"
}'
Example Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"shortUrl": "https://your-domain.com/my-link",
"shortCode": "my-link",
"originalUrl": "https://example.com/very-long-url",
"createdAt": "2025-01-06T12:00:00Z",
"expiresAt": "2025-01-07T12:00:00Z"
}
GET
/api/links/user/links
Get all links with pagination
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page |
number | 1 | Page number |
limit |
number | 50 | Results per page (max 100) |
Example Response
{
"links": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"shortUrl": "https://your-domain.com/abc123",
"originalUrl": "https://example.com",
"clickCount": 42,
"createdAt": "2025-01-06T12:00:00Z",
"category": "marketing",
"hasPassword": false
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 150,
"pages": 3
}
}
GET
/api/links/:id/qr
Generate QR code for a link
Example Response
{
"qrCode": "data:image/png;base64,iVBORw0KGgoAAAANS..."
}
DELETE
/api/links/:id
Deactivate a link
Example Response
{
"message": "Link deactivated successfully"
}
GET
/api/analytics/link/:linkId
Get detailed analytics for a link
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
timeframe |
string | 7d | Time period: 24h, 7d, 30d, all |
Example Response
{
"link": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"shortCode": "abc123",
"originalUrl": "https://example.com",
"totalClicks": 42
},
"analytics": {
"recentClicks": 15,
"clicksByDay": {
"2025-01-06": 5,
"2025-01-05": 10
},
"clicksByHour": [0, 2, 5, 3, ...],
"topReferrers": [
{"referrer": "google.com", "count": 20}
],
"devices": [
{"device": "desktop", "count": 30}
]
}
}
Error Responses
All errors return appropriate HTTP status codes and JSON error messages:
{
"error": "Invalid URL format"
}
| Status Code | Description |
|---|---|
400 |
Bad Request - Invalid parameters |
404 |
Not Found - Resource doesn't exist |
409 |
Conflict - Custom alias already taken |
429 |
Too Many Requests - Rate limit exceeded |
500 |
Internal Server Error |
SDKs & Libraries
Coming soon! We're working on official SDKs for:
JavaScript/Node.js
Python
PHP
Ruby
Go