API Reference

The Admin API runs on port 9090 (localhost only by default). The redirect endpoint runs on port 8081 (public).

Admin API — URL Mappings

Create Short URL

POST /api/shorten

Request body:

{
  "originalUrl": "https://example.com/very/long/path",
  "alias": "my-link",
  "expiresAt": "2025-12-31T23:59:59Z"
}

Response 201 Created:

{
  "shortCode": "my-link",
  "originalUrl": "https://example.com/very/long/path",
  "active": true,
  "createdAt": "2025-01-01T10:00:00Z",
  "expiresAt": "2025-12-31T23:59:59Z"
}

List Mappings

Response 200 OK:

[
  {
    "shortCode": "my-link",
    "originalUrl": "https://example.com/very/long/path",
    "active": true,
    "createdAt": "2025-01-01T10:00:00Z"
  }
]

Edit Mapping

POST /api/edit

{
  "shortCode": "my-link",
  "originalUrl": "https://new-target.com",
  "active": true
}

Delete Mapping

POST /api/delete

{ "shortCode": "my-link" }

Toggle Active

POST /api/toggleActive

{ "shortCode": "my-link" }

Admin API — Import / Export

Export

GET /api/list/export

Downloads a ZIP archive containing all mappings as JSON.

Validate Import

POST /api/list/import/validate
Content-Type: multipart/form-data

Returns validation results before applying. Detects conflicts and invalid entries.

Apply Import

POST /api/list/import/apply

Applies a previously validated import staging.

Check Staging

Admin API — Statistics

Hourly response example:

{
  "shortCode": "my-link",
  "buckets": [
    { "hour": "2025-01-01T10:00:00Z", "count": 42 },
    { "hour": "2025-01-01T11:00:00Z", "count": 17 }
  ]
}

Admin API — Preferences

Admin API — Store Info

GET /api/store/info

Returns metadata about the active storage backend (type, record count, last modified).

Redirect Endpoint

GET /{shortCode}

Ports: 8081 — public-facing, no authentication.

Records a RedirectEvent (timestamp, User-Agent, Referer, IP hash, Accept-Language) on every successful redirect.

Error Responses

All error responses use a consistent JSON envelope:

{
  "error": "ALIAS_ALREADY_EXISTS",
  "message": "The alias 'my-link' is already in use.",
  "status": 409
}