little-co.de
API

API Docs

Shorten URLs from your terminal, CI job, or app.

Shorten a URL

POST a JSON body containing the URL you want shortened. Returns the short URL and metadata.

cURL

curl -X POST https://{@host}/api/links \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/some/very/long/path"}'

HTTP

POST /api/links HTTP/1.1
Host: {@host}
Content-Type: application/json

{"url":"https://example.com/some/very/long/path"}

Response

HTTP/1.1 201 Created
Location: https://{@host}/l/abc12
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1783685040
Content-Type: application/json

{
"data": {
"hash": "abc12",
"slug": null,
"url": "https://example.com/some/very/long/path",
"short_url": "https://{@host}/l/abc12",
"views": 0,
"created_at": "2026-07-10T12:00:00Z"
}
}

Following a short link

Every shortened URL is served as a 302 redirect to the original target. Auto-generated links live at /l/<hash> and custom slugs live at /c/<slug>. Both track a view counter server-side. 

curl -I https://{@host}/l/abc12
# HTTP/1.1 302 Found
# location: https://example.com/some/very/long/path

Rate limits

Link creation is capped at 30 requests per minute per IP. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix seconds), and, on 429s, Retry-After so polite clients can back off.

Custom slugs (admin only)

This instance can also mint short links with a human-readable slug — e.g. /c/summer-sale instead of /l/abc12. Because slugs are scarce and abuseable, they are gated behind a server-configured admin secret. The server operator sets an ADMIN_KEY env var; when it's blank the feature is disabled entirely.

If you're not the server operator, ask them whether an admin key is available and, if so, they'll share it out-of-band. You can also self-host your own instance and set the key yourself — see github.com/lubien/little-code.

Pass the key via the ?admin= query string. Anything else in the body works exactly as before, except that a slug field is now accepted. 

curl -X POST "https://{@host}/api/links?admin=YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/summer-sale","slug":"summer-sale"}'

# HTTP/1.1 201 Created
# Location: https://{@host}/c/summer-sale
# {"data":{"hash":"...","slug":"summer-sale","short_url":"https://{@host}/c/summer-sale",...}}

Slugs must be 2–50 lowercase letters, digits, or dashes; can't start or end with a dash; and can't be one of a small reserved list.

Errors

All errors are JSON. The most common ones:

  • 422 Unprocessable Entity — validation failed (missing / invalid URL, slug taken, etc.)
  • 429 Too Many Requests — rate limit exceeded. Wait for the Retry-After header.
  • 400 Bad Request — malformed JSON body.