Guide · Business

How to Use the TraceNull API & Custom Domains

Published April 2026 · 8 min read · By the TraceNull Team

TraceNull's Business plan gives you two powerful features beyond the standard link shortener: a REST API for creating and managing links programmatically, and custom domains that make every short link appear to come from your own domain instead of tracenull.cc. This guide walks through both from start to finish.

Both features require a Business plan. Custom domains are limited to 5 per account. The API uses your personal API key from the dashboard.

Part 1: Setting Up a Custom Domain

With a custom domain, your short links look like links.yoursite.com/abc instead of tracenull.cc/abc. Visitors see your brand, not ours. The referrer stripping and all other TraceNull features still apply.

Step 1 — Add your domain in the dashboard

Log in and go to your dashboard. Scroll to the Custom Domains section. Enter your subdomain (e.g. links.yourdomain.com) and click Add Domain. TraceNull will generate a unique verification token for you.

Step 2 — Set two DNS records

Type	Name / Host	Value / Target
CNAME	links (your subdomain)	tracenull.cc
TXT	@ (root domain)	tracenull-verify=your-token-here

The CNAME points your subdomain's traffic to TraceNull's servers. The TXT record proves you own the domain.

Step 3 — Verify

DNS changes can take anywhere from a few minutes to 48 hours to propagate — most registrars apply them within 5–15 minutes. Once your DNS is live, click Verify in the dashboard. TraceNull checks for the TXT record automatically.

Step 4 — Done

After verification, TraceNull automatically issues a TLS certificate for your domain via Caddy. Any new short links you create will use your custom domain URL. Existing links continue to work on tracenull.cc.

Tip: You can verify up to 5 custom domains per account. Each verified domain gets its own TLS certificate — HTTPS is always on, no configuration needed.

Common issues

Verification fails immediately — DNS hasn't propagated yet. Wait 10–15 minutes and try again.
CNAME won't save at root (@) — Use a subdomain like links. instead. Root CNAMEs conflict with other records on most registrars.
Cloudflare proxy (orange cloud) — Set the CNAME to DNS-only (grey cloud) so TraceNull can issue a certificate correctly.

For registrar-specific screenshots and a full troubleshooting list, see the Custom Domain Setup Guide →

Part 2: Using the REST API

The TraceNull API lets you create short links, list your links, view analytics, and delete links — all without touching the dashboard. It's useful for automating link creation in your own tools, CMS workflows, or scripts.

Getting your API key

In your dashboard, scroll to the API Access section. Click Generate API Key. Your key looks like tn_ followed by 48 hex characters. Copy it — you'll only see it once after generation. You can rotate or revoke it at any time.

Keep your API key private. Anyone with your key can create and delete links on your account. If it's compromised, rotate it immediately in the dashboard.

Making your first request

All API requests use the X-Api-Key header for authentication. Here's a minimal example to create a short link:

curl -X POST https://tracenull.cc/api/shorten \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: tn_your_key_here" \
  -d '{"url": "https://example.com/your-long-url"}'

Response:

{
  "slug": "ab3x",
  "short_url": "https://tracenull.cc/ab3x",
  "custom_url": "https://links.yourdomain.com/ab3x",
  "destination": "https://example.com/your-long-url",
  "expires_at": "2027-04-03 12:00:00",
  "ttl_days": 365
}

If you have a verified custom domain, custom_url contains the branded link. Use whichever you prefer.

Available endpoints

POST /api/shorten — Create a short link (supports UTM params, custom expiry, password)
GET /api/my/links — List all your short links
GET /api/my/links/:slug/analytics — Click analytics for a specific link
DELETE /api/my/links/:slug — Delete a link

For full parameter documentation, response shapes, error codes, and code examples in JavaScript, Python, and PHP, see the Full API Reference →

Adding UTM parameters

Business users can attach UTM tracking parameters at link creation time. TraceNull injects them into the destination URL before storing the link:

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

The destination stored is https://example.com/product?utm_source=newsletter&utm_medium=email&utm_campaign=april-launch — so your analytics platform receives the full attribution data on every click.

Setting a custom expiry

By default, Business links last 365 days. You can set a shorter (or longer, up to the plan maximum) expiry with the expires_at field:

{
  "url": "https://example.com/sale",
  "expires_at": "2026-05-01T00:00:00.000Z"
}

JavaScript example

const response = await fetch('https://tracenull.cc/api/shorten', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'tn_your_key_here'
  },
  body: JSON.stringify({
    url: 'https://example.com/page',
    utm_source: 'myapp',
    utm_medium: 'api'
  })
});

const link = await response.json();
console.log(link.custom_url || link.short_url);
// → https://links.yourdomain.com/ab3x

Rate limits

The /api/shorten endpoint is rate-limited to 1 request per minute, 20 per hour, and 50 per 12 hours. These limits apply per IP address. If you hit a limit, you'll receive a 429 Too Many Requests response — implement a retry with backoff in your integration.

Ready to get started?

Full API reference and custom domain setup guide are available in the docs.

API Reference → Custom Domain Guide →