API Reference

The TraceNull API lets you create and manage short links programmatically. It's a simple REST API — all requests use JSON, all responses are JSON. Available exclusively on the Business plan.

Authentication

Every request must include your API key in the X-Api-Key header. You can find and manage your key in the Dashboard → API Access section.

X-Api-Key: tn_a1b2c3d4e5f6...

Base URL

https://tracenull.cc

All endpoints are relative to this base URL. HTTPS only.

Rate Limits

The shorten endpoint is shared with the web dashboard and applies the same limits:

• 1 request per minute
• 20 requests per hour
• 50 requests per 12 hours

When a rate limit is hit, the API returns 429 Too Many Requests with an error message explaining when you can retry.

Shorten URL

{
  "slug":        "ab3x",
  "short_url":   "https://tracenull.cc/ab3x",
  "custom_url":  "https://yourdomain.com/ab3x",  // null if no custom domain
  "destination": "https://example.com/?utm_source=newsletter",
  "expires_at":  "2025-12-31 23:59:59",
  "ttl_days":    365
}

curl -X POST https://tracenull.cc/api/shorten \
  -H "X-Api-Key: tn_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/sneakers",
    "expires_at": "2025-12-31",
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "winter-sale"
  }'

List Links

[
  {
    "slug":         "ab3x",
    "destination":  "https://example.com/",
    "clicks":       142,
    "expires_at":   "2025-12-31 00:00:00",
    "created_at":   "2025-06-01 10:22:00",
    "has_password": 0  // 1 if password-protected
  },
  ...
]

curl https://tracenull.cc/api/my/links \
  -H "X-Api-Key: tn_your_key_here"

Delete Link

{ "ok": true }

curl -X DELETE https://tracenull.cc/api/my/links/ab3x \
  -H "X-Api-Key: tn_your_key_here"

Click Analytics

{
  "slug":   "ab3x",
  "total":  142,    // all-time clicks
  "daily": [         // only days with at least 1 click
    { "day": "2025-06-01", "count": 23 },
    { "day": "2025-06-02", "count": 41 },
    ...
  ]
}

curl https://tracenull.cc/api/my/links/ab3x/analytics \
  -H "X-Api-Key: tn_your_key_here"

Error Codes

All errors return a JSON body with an error field describing the problem.

Error response shape

{ "error": "Invalid URL" }

Full Examples

JavaScript (fetch)

const API_KEY = 'tn_your_key_here';

// Create a short link
async function shorten(url, utm = {}) {
  const res = await fetch('https://tracenull.cc/api/shorten', {
    method: 'POST',
    headers: {
      'X-Api-Key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url, ...utm }),
  });
  if (!res.ok) throw new Error((await res.json()).error);
  return res.json();
}

// Usage
const link = await shorten(
  'https://example.com/product',
  { utm_source: 'newsletter', utm_medium: 'email' }
);
console.log(link.short_url); // https://tracenull.cc/ab3x

Python (requests)

import requests

API_KEY = "tn_your_key_here"
HEADERS = {"X-Api-Key": API_KEY, "Content-Type": "application/json"}

# Create a short link
r = requests.post("https://tracenull.cc/api/shorten", json={
    "url": "https://example.com/product",
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "launch-2025",
}, headers=HEADERS)
r.raise_for_status()
print(r.json()["short_url"])

# List all links
links = requests.get("https://tracenull.cc/api/my/links", headers=HEADERS).json()
for link in links:
    print(f"{link['slug']}  →  {link['destination']}  ({link['clicks']} clicks)")

PHP (curl)

$apiKey = 'tn_your_key_here';

$ch = curl_init('https://tracenull.cc/api/shorten');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => [
    'X-Api-Key: ' . $apiKey,
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'url'          => 'https://example.com/',
    'utm_source'   => 'newsletter',
    'utm_medium'   => 'email',
  ]),
]);
$response = json_decode(curl_exec($ch), true);
echo $response['short_url'];