API reference

All paths are relative to the path in base_url. Every frontend, API, metadata, deletion, and short-code route accepts trailing slashes, including when a query string follows the slash.

Health and frontend

GET / serves the embedded frontend when production=false.
GET /api/health returns HTTP 200:

{"status": "ok", "service": "url-shortener"}

With a non-empty base path, requesting the bare path redirects to its trailing slash form; for example, /s redirects to /s/.

Create a short URL

POST /api/shorten and GET /api/shorten are supported without an API key. Fields may be supplied as query parameters or in a JSON body; query parameters take precedence.

Field	Required	Description
`url`	yes	Absolute `http://` or `https://` URL.
`retention_days`	no	Per-URL lifetime, or zero to keep forever.

Success is HTTP 201 with only the short URL as UTF-8 plain text:

https://example.com/s/aB3xYz

Codes begin at min_short_length. After ten collisions at one length, ushort tries the next length through max_short_length.

List URLs

GET /api/urls?api_key=<key> returns all rows newest first. A missing or invalid key returns HTTP 403 with an empty body.

{
  "count": 1,
  "urls": [
    {
      "short_code": "aB3xYz",
      "short_url": "https://example.com/s/aB3xYz",
      "original_url": "https://example.org",
      "created_at": 1710000000,
      "visit_count": 5,
      "retention_days": 30
    }
  ]
}

Metadata and lookup

GET /api/urls/<code> returns one metadata object without authentication.
GET /api/lookup?url=<encoded-url> returns the newest matching metadata object without authentication.
A missing record returns HTTP 404 with an empty body.

Delete

DELETE /api/urls/<code>?api_key=<key> returns:

HTTP 204 with an empty body on success;
HTTP 404 with an empty body when the code does not exist; or
HTTP 403 with an empty body when authentication fails.

Redirect

GET /<code> atomically increments visit_count and responds with HTTP 302 to the stored original URL.

Every response includes the compatibility CORS and security headers.

2.2 KiB Raw Blame History