Detailed API reference for developers to integrate with our URL shortener.

Create Short Link

POST /api/v1/shorten
Content-Type: application/json

Request:

{
  "url": "https://example.com",
  "type": "random", // or "alias"
  "alias": "mycustom", // required if type is "alias" (5-15 chars)
  "isLimited": false,
  "limitation_type": "time", // "time", "clicks", or "both"
  "expires_in": 7, // days
  "max_clicks": 100,
  "isProtected": false,
  "password": "mypassword"
}
      

Response:

{
  "status": "success",
  "short_url": "mycustom",
  "monitor_url": "m/AbCdEfGhIj"
}
      

Redirect to Original URL

GET /{short_url}

Returns:

302 Found
Location: https://example.com
      

Unlock Protected Link

POST /api/v1/{short_url}

Request:

{
  "password": "mypassword"
}
      

Response:

{
  "url": "https://example.com"
}
      

List Authenticated User's Links

GET /api/v1/my-links
Authorization: Bearer <token> or Cookie: sid

Response:

[
  {
    "data": {
      "short_url": "mycustom",
      "long_url": "https://example.com",
      "clicks": 42,
      "unique_clicks": 30,
      "created_at": "2026-07-12T10:00:00Z",
      "is_protected": false,
      "max_clicks": null,
      "expires_at": null
    },
    "clicks": [
      {
        "time_of_click": "2026-07-12T14:30:00Z",
        "country": "EG",
        "user_agent": "Mozilla/5.0 ...",
        "referer": "https://google.com",
        "ip_hash": "a1b2c3..."
      }
    ]
  }
]
      

Get Link Analytics Details

GET /api/v1/my-links/{short_url}/details
Authorization: Bearer <token> or Cookie: sid

Response:

{
  "clicks": 152,
  "unique_clicks": 120,
  "countries": { "EG": 120, "US": 32 },
  "referrers": { "Direct": 100, "Google": 52 },
  "browsers": { "Chrome": 150, "Safari": 2 },
  "platforms": { "Windows": 100, "iOS": 52 },
  "dates": { "2026-07-12": 152 },
  "linkData": { /* Link object */ }
}
      

Delete Authenticated Link

DELETE /api/v1/my-links/{short_url}
Authorization: Bearer <token> or Cookie: sid

Response:

{
  "status": "success"
}
      

Delete Anonymous Link (Via Monitor Key)

DELETE /api/v1/{short_url}/{monitor_key}

Response:

{
  "status": "success"
}
      

Get Anonymous Link Analytics

GET /{short_url}/{monitor_key}

Returns (JSON if Accept header is not text/html):

{
  "data": { /* link record */ },
  "clicks": [...]
}
      

System Health Check

GET /api/v1/health

Response (JSON if header Accept: application/json):

{
  "status": "healthy",
  "database": "connected",
  "timestamp": "OK"
}
      

Response (HTML if header Accept: text/html):

Returns a status dashboard page summarizing database connectivity, platform runtime, and database latency.

---

Rate Limits

All rate limits are per minute, per IP address.

• Shorten Endpoint (/api/v1/shorten):
  • Anonymous: 10 requests / minute
  • Authenticated: 20 requests / minute
• All other endpoints:
  • 10 requests / minute (all users)

Error Responses (Examples)

{ "error": "reserved_alias" }
      

{ "error": "alias_already_exists" }
      

{ "error": "validation_failed", "details": [...] }