API Documentation
Integrate QuickLink into your applications
Shorten URL
POST/api/shortenCreate a shortened URL. Rate limit: 20 requests/minute per IP.
Request Body:
{
"targetUrl": "https://example.com/very/long/url",
"customAlias": "my-link" // optional
}
Response:
{
"short": "abc1234",
"url": "https://example.com/very/long/url"
}Analytics Overview
GET/api/analytics/overviewGet aggregated analytics for all your links. Requires authentication.
Query Parameters:
?period=7d // 24h, 7d, 30d, 90d (default: 7d)
&exclude_bots=true // Exclude bot traffic (optional)
&start_date=2024-01-01 // Custom date range start (optional)
&end_date=2024-01-31 // Custom date range end (optional)
Response:
{
"totalClicks": 1234,
"uniqueClicks": 856,
"period": "7d",
"clicksOverTime": {
"2024-01-01": 150,
"2024-01-02": 200,
"2024-01-03": 180
},
"devices": {
"mobile": 800,
"desktop": 400,
"tablet": 34
},
"os": {
"macOS": 450,
"Windows": 300,
"iOS": 250,
"Android": 234
},
"browsers": {
"Chrome": 600,
"Safari": 400,
"Firefox": 150,
"Edge": 84
},
"countries": {
"United States": 500,
"United Kingdom": 200,
"Canada": 150
},
"referrers": {
"google.com": 300,
"twitter.com": 150,
"direct": 100
},
"clicksByHour": {
"9": 50,
"10": 75,
"14": 100,
"17": 80
},
"utmCampaigns": {
"summer_sale": {
"count": 200,
"source": "email",
"medium": "newsletter"
}
}
}Link-Specific Analytics
GET/api/analytics/[shortCode]Get detailed analytics for a specific link. Requires link ownership.
Query Parameters:
?days=30 // Number of days (default: 30)
&exclude_bots=true // Exclude bot traffic (optional)
&start_date=2024-01-01 // Custom date range start (optional)
&end_date=2024-01-31 // Custom date range end (optional)
&format=csv // Export as CSV (optional, default: json)
Response (JSON):
{
"shortCode": "abc1234",
"totalClicks": 42,
"uniqueClicks": 35,
"clicksOverTime": {
"2024-01-01": 10,
"2024-01-02": 15,
"2024-01-03": 17
},
"devices": {
"mobile": 20,
"desktop": 18,
"tablet": 4
},
"os": {
"macOS": 15,
"Windows": 12,
"iOS": 10,
"Android": 5
},
"browsers": {
"Chrome": 25,
"Safari": 12,
"Firefox": 5
},
"countries": {
"United States": 20,
"United Kingdom": 12,
"Canada": 10
},
"referrers": {
"google.com": 15,
"twitter.com": 10,
"direct": 17
},
"clicksByHour": {
"9": 5,
"10": 8,
"14": 12,
"17": 10
},
"utmCampaigns": {
"summer_sale": {
"count": 15,
"source": "email",
"medium": "newsletter"
}
},
"recentClicks": [
{
"timestamp": "2024-01-03T10:30:00Z",
"deviceType": "desktop",
"browser": "Chrome",
"os": "macOS",
"country": "United States",
"city": "San Francisco",
"referrer": "google.com",
"utmCampaign": "summer_sale",
"isUnique": true,
"isBot": false
}
]
}
Response (CSV):
Timestamp,Device Type,Browser,OS,Country,Region,City,Referrer,UTM Source,UTM Medium,UTM Campaign,Is Unique,Is Bot,Visitor ID
2024-01-03T10:30:00Z,desktop,Chrome,macOS,United States,California,San Francisco,google.com,email,newsletter,summer_sale,Yes,No,visitor_123Dashboard Statistics
GET/api/dashboard/statsGet dashboard statistics. Requires authentication.
Response:
{
"totalLinks": 150,
"totalClicks": 5420,
"activeLinks": 45,
"clicksToday": 23,
"changes": {
"links": "+12.5%",
"clicks": "+8.3%",
"active": "+5%",
"today": "+15%"
}
}List Links
GET/api/internal/listGet all links for the authenticated user.
Response:
[
{
"shortCode": "abc1234",
"targetUrl": "https://example.com",
"clicks": 42,
"createdAt": "2024-01-01T00:00:00.000Z",
"custom": false,
"title": "Example Link"
}
]Link Management
DELETE/api/links/[shortCode]Delete a link. Requires link ownership.
Response:
{
"success": true,
"message": "Link deleted successfully"
}Health Check
GET/api/healthCheck API health and status.
Response:
{
"status": "ok",
"timestamp": "2024-01-01T00:00:00.000Z",
"version": "1.0.0"
}API Authentication
For authenticated endpoints, include your session cookie or API key:
Headers: Cookie: session=your_session_cookie # OR for API v1 Authorization: Bearer YOUR_API_KEY # OR X-API-Key: YOUR_API_KEY
Get your API key from Settings
Rate Limits
Public API: 20 requests per minute per IP
Authenticated API: 100 requests per minute per user
Analytics Endpoints: No special rate limits, but use reasonable request intervals
Error Responses
Error Response Format:
{
"error": "Error message",
"code": "ERROR_CODE" // optional
}
Common Error Codes:
- UNAUTHORIZED: Authentication required
- FORBIDDEN: Insufficient permissions
- NOT_FOUND: Resource not found
- RATE_LIMIT_EXCEEDED: Too many requests
- INVALID_URL: Invalid URL format
- ALIAS_EXISTS: Custom alias already taken
- MISSING_URL: URL parameter required