URL shortener API

Create a link

POST /links returns 201 with the new 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"
  }'

The response is the link object:

{
  "id": "6f1c0b52-…",
  "address": "spring-sale",
  "target": "https://example.com/a/very/long/url",
  "description": "Q2 campaign",
  "expire_in": "2026-09-30T10:00:00.000Z",
  "password": true,
  "visit_count": 0,
  "created_at": "2026-09-23T10:00:00.000Z",
  "updated_at": "2026-09-23T10:00:00.000Z",
  "link": "https://xlyl.link/spring-sale"
}

password comes back as a boolean — true here, because the request set one — never the value itself. Links also carry banned and, when they are on a custom domain, domain with its address.

Create a link on your own domain

Connect the domain first (see Domains), then pass its address — the host name alone, no scheme or path — in domain:

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/launch",
    "customurl": "launch",
    "domain": "go.example.com"
  }'

The response's domain is go.example.com and link is the short link on it. A domain that is not on your account is refused with 400 and You can't use this domain.

List, search and paginate

curl "https://xlyl.link/api/v2/links?limit=50&skip=50&sortBy=visit_count%20DESC&search=campaign" \
  -H "X-API-Key: YOUR_API_KEY"

The response wraps a page of link objects with the numbers you need to fetch the next one:

{
  "total": 132,
  "limit": 50,
  "skip": 50,
  "data": [ { "id": "6f1c0b52-…", "address": "spring-sale", … } ]
}

Keep adding limit to skip until it reaches total.

Edit a link

PATCH /links/:id takes any of target, address (the alias), description, expire_in and password, with the same rules as creation, and returns the updated link. At least one is required. A password or expiry can be set or changed but not removed, and the domain cannot be changed.

# 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"}'

Changing the target keeps the short link as it is. Changing address changes the short link: the old one stops working immediately and nothing redirects from it.

Delete a link

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

Returns {"message": "Link has been deleted successfully."}. Its statistics are deleted with it.

Totals for one link

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

Returns the link object plus lastDay (24 hourly buckets), lastWeek (7 days), lastMonth (30 days) and allTime (18 months). Each has views, the clicks per bucket, and stats, lists of { "name", "value" } for browser, os, country and referrer. updatedAt says when they were computed: results are cached for a minute, or five on links with more than 50,000 clicks.

{
  "lastDay": {
    "views": [0, 0, 3, …],
    "stats": {
      "browser": [{ "name": "chrome", "value": 12 }, …],
      "os": [{ "name": "android", "value": 9 }, …],
      "country": [{ "name": "gb", "value": 7 }, …],
      "referrer": [{ "name": "direct", "value": 5 }, …]
    }
  },
  "lastWeek": { … }, "lastMonth": { … }, "allTime": { … },
  "updatedAt": "…",
  "id": "6f1c0b52-…", "address": "spring-sale", "visit_count": 214, …
}

Totals for the account

GET /links/stats returns the same four periods across all of your links, without the link fields. It is built from the last 30 days only — so allTime here covers those 30 days — and is cached for up to 30 minutes.

Insights

GET /links/:id/insights?window=7d reads the per-click detail. window is 24h, 7d (the default), 30d or 90d.

{
  "window": "7d",
  "totals": { "clicks": 214, "visitors": 180 },
  "series": [{ "at": "2026-09-17T00:00:00.000Z", "clicks": 30, "visitors": 26 }, …],
  "breakdowns": {
    "country": [{ "name": "GB", "count": 90 }, …, { "name": "Other", "count": 12 }],
    "utm_campaign": [{ "name": "spring", "count": 120 }],
    …
  },
  "filtered": [{ "name": "bot", "count": 41 }, { "name": "repeat", "count": 9 }],
  "id": "6f1c0b52-…", "address": "spring-sale", …
}

breakdowns has country, region, city, device, browser, browser_version, os, os_version, referrer, referrer_url, channel, language, app (the app the link was opened in, when known) and the five utm_* tags; each lists its top six values, with the rest folded into Other. Per-click detail is kept for 365 days.

Every number above counts people only. filtered counts the clicks left out, by reason: bot (a self-declared crawler, preview fetcher or script), preview (a prefetch or HEAD request), not-a-page (fetched or embedded rather than opened), no-language (no Accept-Language), spoofed (a browser string without that browser's headers), datacenter (a cloud server) and repeat (the same visitor within 30 seconds). At most 1,000 filtered clicks are kept per link per day, so on a link under heavy bot traffic it is a lower bound.

Recent clicks

GET /links/:id/visits?limit=50 returns the newest clicks, 50 by default and at most 200, as { "visits": [...] }. Each has created_at, country, city, device, browser, os, referrer_host, app, channel, utm_source, utm_campaign and is_unique. Filtered clicks are not included.

Export clicks as CSV

curl -o clicks.csv "https://xlyl.link/api/v2/links/LINK_ID/visits.csv?days=365" \
  -H "X-API-Key: YOUR_API_KEY"

days is 30 by default and at most 365, and one file holds at most 50,000 clicks, newest first. Columns: time, location (country, region, city), device, browser and OS with versions, channel, referrer host and full referrer URL, the five UTM tags, language, app, is_unique and filtered_reason. Filtered clicks are included so the filter can be checked; an empty filtered_reason is a counted click. It can only go as far back as per-click detail is kept (365 days).

Add a domain

curl -X POST https://xlyl.link/api/v2/domains \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "go.example.com", "homepage": "https://example.com"}'

address is required, 3–64 characters; a leading www. is dropped. It cannot be xlyl.link or a domain already on an account. homepage, optional, is where visitors are sent when they open the domain itself or an address on it with no link. Returns 201:

{
  "id": "0b7e41d2-…",
  "address": "go.example.com",
  "homepage": "https://example.com",
  "check_status": null,
  "checked_at": null,
  "created_at": "2026-09-23T10:00:00.000Z",
  "updated_at": "2026-09-23T10:00:00.000Z"
}

Adding the domain does not set up its DNS; the custom domain guide covers that.

Check a domain

GET /domains/:id/check requests the domain itself, reads its DNS to explain any failure, and stores the outcome:

{
  "address": "go.example.com",
  "status": "working",
  "ok": true,
  "expected": { "ip": "…", "cname": null },
  "a": ["…"],
  "cname": [],
  "error": null,
  "checkedAt": "2026-09-23T10:05:00.000Z"
}

Remove a domain

DELETE /domains/:id removes the domain from your account and returns {"message": "Domain deleted successfully"}.