URL shortener API

Getting an API key#

Sign in, open API key and generate a key. The key is shown once, at the moment it is created — only a hash of it is stored, so it cannot be recovered later. If you lose it, generate a new one; the old key stops working immediately.

Treat it like a password. It authenticates as your account, so keep it server-side and never ship it in client-side JavaScript.

Authentication#

Send the key in an X-API-Key header:

curl https://xlyl.link/api/v2/links \
  -H "X-API-Key: YOUR_API_KEY"

A JWT from the login endpoint also works, as Authorization: Bearer <token>, which is what the web interface itself uses.

Creating a link#

curl -X POST https://xlyl.link/api/v2/links \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "https://example.com/a/very/long/url",
    "customurl": "spring-sale",
    "description": "Q2 campaign",
    "expire_in": "7 days",
    "password": "optional"
  }'

Only target is required. The response contains the short link and its id:

{
  "id": "6f1c…",
  "address": "spring-sale",
  "target": "https://example.com/a/very/long/url",
  "link": "https://xlyl.link/spring-sale",
  "password": false,
  "visit_count": 0
}

Note that password comes back as a boolean, never the value — the API does not echo secrets.

Listing and searching#

curl "https://xlyl.link/api/v2/links?limit=25&skip=0&search=campaign" \
  -H "X-API-Key: YOUR_API_KEY"

limit is capped at 50 per page; use skip to paginate. search matches the description, alias, target and domain. sortBy accepts a column and a direction, for example visit_count DESC.

Editing and deleting#

# change where an existing link points
curl -X PATCH https://xlyl.link/api/v2/links/LINK_ID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "https://example.com/new-destination"}'

# delete it
curl -X DELETE https://xlyl.link/api/v2/links/LINK_ID \
  -H "X-API-Key: YOUR_API_KEY"

Reading statistics#

curl https://xlyl.link/api/v2/links/LINK_ID/stats \
  -H "X-API-Key: YOUR_API_KEY"

Returns lastDay, lastWeek, lastMonth and allTime, each with a view count per bucket and totals broken down by browser, operating system, country and referrer.

Rate limits and errors#

Link creation is rate limited per account. Authentication endpoints are limited more tightly to slow down credential guessing. Exceeding a limit returns 429 with aRetry-After header.

Errors are JSON and use conventional status codes:

Unexpected failures return a requestId alongside the error. Quote it when reporting a problem — it matches the entry in the server logs.

Getting a key#

The API key page issues one and shows it once. The quick-start samples on that page are filled in with your new key, so the first request is a copy and paste rather than an assembly job.

Only a hash of the key is stored, so it cannot be recovered later — if you lose it, generate another, which revokes the previous one immediately. Treat it like a password: it carries full access to your links.

What people build with it#

The common patterns, in rough order of how often they come up:

• A link per record. One short link per customer, order or property, created when the record is, so every outbound message carries a trackable branded link.
• Campaign scaffolding. A spreadsheet of placements in, a short link per placement out, each with its UTM-tagged destination and a description naming the campaign — the method is here.
• CMS integration. Publishing a post creates its share link on your own domain, so the link exists before anyone needs it.
• Reporting. Pulling per-link statistics into a warehouse or a dashboard beside the rest of your numbers.

All of it runs on your own domain if you have connected one, and the links behave exactly like ones made in the dashboard — editable, measurable and revocable.