API Documentation

Integrate QuickLink into your applications

Shorten URL

POST/api/shorten

Create 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/overview

Get 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_123

Dashboard Statistics

GET/api/dashboard/stats

Get 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/list

Get 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/health

Check 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