API Documentation

Programmatic access to the trkm.cc URL shortener.

Endpoints

Create a short link
Get link stats
Delete a link
QR code
Public stats page

Authentication

Admin endpoints require HTTP Basic Auth. Pass your credentials as a base64-encoded user:pass string in the Authorization header.

Authorization: Basic base64(user:pass)

Create a short link

Shorten a URL with optional custom code, UTM parameters, Open Graph overrides, expiry, and click limits.

POST /admin/links Auth required

Parameter	Type	Description
`url`	string required	The destination URL to shorten.
`custom_code`	string optional	Custom short code. Alphanumeric and hyphens. Auto-generated if omitted.
`title`	string optional	A friendly label for the link.
`utm_source`	string optional	UTM source parameter appended to the destination URL.
`utm_medium`	string optional	UTM medium parameter.
`utm_campaign`	string optional	UTM campaign parameter.
`utm_term`	string optional	UTM term parameter.
`utm_content`	string optional	UTM content parameter.
`og_title`	string optional	Custom Open Graph title for social previews.
`og_description`	string optional	Custom OG description.
`og_image`	string optional	Custom OG image URL.
`expires_at`	string optional	Expiry datetime. Format: `YYYY-MM-DD HH:MM:SS`
`max_clicks`	integer optional	Maximum number of clicks before the link expires.
`created_by`	string optional	Creator identifier for auditing.

    Request
POST /admin/links HTTP/1.1
Authorization: Basic dXNlcjpwYXNz
Content-Type: application/json

{
  "url": "https://example.com/landing",
  "custom_code": "spring-sale",
  "title": "Spring Sale 2026",
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "spring2026",
  "utm_term": "deals",
  "utm_content": "cta_button",
  "og_title": "Exclusive Spring Deals",
  "og_description": "Save up to 40% this spring.",
  "og_image": "https://example.com/og-spring.jpg",
  "expires_at": "2026-12-31 23:59:59",
  "max_clicks": 1000,
  "created_by": "trackman"
}
  

    Response 201
{
  "code": "spring-sale",
  "short_url": "https://trkm.cc/spring-sale",
  "url": "https://example.com/landing",
  "title": "Spring Sale 2026",
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "spring2026",
  "created_at": "2026-03-25 10:30:00",
  "expires_at": "2026-12-31 23:59:59",
  "max_clicks": 1000,
  "qr_url": "https://trkm.cc/spring-sale.qr",
  "stats_url": "https://trkm.cc/spring-sale+"
}
  

Get link stats

Retrieve detailed click analytics for a specific short link, including geographic data, devices, referrers, and daily breakdown.

GET /admin/links/{code}/stats?days=30 Auth required

Parameter	Type	Description
`code`	string path	The short link code.
`days`	integer query, optional	Number of days to look back. Default: `30`

    Request
GET /admin/links/spring-sale/stats?days=30 HTTP/1.1
Authorization: Basic dXNlcjpwYXNz
  

    Response 200
{
  "link": {
    "code": "spring-sale",
    "url": "https://example.com/landing",
    "title": "Spring Sale 2026",
    "created_at": " 2026-03-25 10:30:00"
  },
  "total_clicks": 482,
  "unique_visitors": 371,
  "daily": [
    { "day": "2026-03-24", "clicks": 42 },
    { "day": "2026-03-25", "clicks": 67 }
  ],
  "countries": [
    { "country": "France", "clicks": 210 },
    { "country": "United States", "clicks": 98 }
  ],
  "devices": [
    { "device": "Mobile", "clicks": 305 },
    { "device": "Desktop", "clicks": 177 }
  ],
  "referrers": [
    { "referer": "https://mail.google.com", "clicks": 152 }
  ],
  "browsers": [
    { "browser": "Chrome", "clicks": 280 }
  ]
}
  

Delete a link

Permanently remove a short link and all associated click data.

DELETE /admin/links/{code} Auth required

Parameter	Type	Description
`code`	string path	The short link code to delete.

    Request
DELETE /admin/links/spring-sale HTTP/1.1
Authorization: Basic dXNlcjpwYXNz
  

    Response 200
{
  "ok": true,
  "deleted": "spring-sale"
}
  

QR Code

Generate a QR code PNG image for any short link. No authentication required.

GET /{code}.qr?size=10 No auth

Parameter	Type	Description
`code`	string path	The short link code.
`size`	integer query, optional	Module size in pixels (1–20). Default: `10`

    Request
GET /spring-sale.qr?size=10 HTTP/1.1
  

    Response 200
Content-Type: image/png

<binary PNG data>
  

Public stats page

View a human-readable stats dashboard for any short link. No authentication required for public links.

GET /{code}+ No auth

Parameter	Type	Description
`code`	string path	The short link code, followed by `+`.

    Request
GET /spring-sale+ HTTP/1.1
  

    Response 200
Content-Type: text/html

<!-- Full HTML stats dashboard with charts, geo data, device breakdown -->
  