urlr API

A small REST API for creating and managing short links. JSON in, JSON out. Base URL:

https://urlr.io/api

Every request needs an API key (see Authentication). All responses are JSON with a standard shape on error.

Authentication

Pass your API key as a Bearer token in the Authorization header. Find your key in Settings → API. Keep it secret — treat it like a password.

Authorization: Bearer urlr_live_sk_7f3a9c2e8b41d0f6a29c

POSTCreate a Link

POST /api/links — create a short link. Body accepts url (required), and optionally alias, expiresAt, and maxClicks.

curl

curl -X POST https://urlr.io/api/links \
  -H "Authorization: Bearer urlr_live_sk_7f3a9c2e8b41d0f6a29c" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/a/very/long/path","alias":"launch"}'

JavaScript

await fetch("https://urlr.io/api/links", {
  method: "POST",
  headers: {
    "Authorization": "Bearer urlr_live_sk_7f3a9c2e8b41d0f6a29c",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ url: "https://example.com", alias: "launch" })
});

Response 201 Created

{
  "id": 4812,
  "shortCode": "launch",
  "shortUrl": "https://urlr.io/launch",
  "originalUrl": "https://example.com/a/very/long/path",
  "clickCount": 0,
  "createdAt": "2026-07-08T14:22:05Z"
}

GETGet Link Stats

GET /api/links/:id — return a link plus its aggregated analytics.

curl https://urlr.io/api/links/4812 \
  -H "Authorization: Bearer urlr_live_sk_7f3a9c2e8b41d0f6a29c"

Response 200 OK

{
  "id": 4812,
  "shortUrl": "https://urlr.io/launch",
  "totalClicks": 4812,
  "topReferrer": "twitter.com",
  "topCountry": "US",
  "devices": { "mobile": 61, "desktop": 33, "tablet": 6 }
}

GETList Links

GET /api/links — list your links, most recent first. Paginate with ?page= and ?limit= (max 100).

curl "https://urlr.io/api/links?page=1&limit=20" \
  -H "Authorization: Bearer urlr_live_sk_7f3a9c2e8b41d0f6a29c"

Response 200 OK

{
  "page": 1,
  "limit": 20,
  "total": 5,
  "links": [
    { "id": 6730, "shortCode": "insta-bio", "clickCount": 6730 },
    { "id": 4812, "shortCode": "launch", "clickCount": 4812 }
  ]
}

DELETEDelete a Link

DELETE /api/links/:id — permanently delete a link and its click history.

curl -X DELETE https://urlr.io/api/links/4812 \
  -H "Authorization: Bearer urlr_live_sk_7f3a9c2e8b41d0f6a29c"

Response 200 OK

{ "success": true }

Rate Limits

Limits are per API key. Exceeding a limit returns 429 Too Many Requests with a Retry-After header.

Tier	Requests / hour	Link creation
Free	100	100 / hour
Pro soon	1,000	1,000 / hour
Team soon	5,000	5,000 / hour

Errors

Errors use standard HTTP status codes and a consistent JSON body.

{
  "error": "That alias is already taken."
}

Status	Meaning
400	Bad request — invalid or missing fields
401	Missing or invalid API key
404	Link not found
409	Alias already taken
429	Rate limit exceeded