API Documentation

Overview

Base URL: https://shrtnlnk.com

JSON endpoints accept Content-Type: application/json or application/x-www-form-urlencoded.

Method	Path	Purpose
POST	`/api/links`	Recommended — store a short link (no CSRF)
GET	`/api/links/{code}`	Get link details and click count
PATCH	`/api/links/{code}`	Update an existing short link
POST	`/shorten`	Web UI shorten (CSRF required from browser)
GET	`/s/{code}`	Bridge cloaking page, then destination

Link cloaking: Set url_cloak: 1 (default) for a bridge page with preview; set url_cloak: 0 for an instant 302 redirect to the destination.

Authentication

No API keys or tokens are required by default. If you expose the API publicly, protect /api/* at the firewall or API gateway level.

Create short link (API)

Create a new short link or return an existing one when the same URL was already shortened (see deduplication).

POST /api/links

Body parameters

Parameter	Type	Required	Description
`original_url`	string (URL)	Yes	Destination URL (max 2048 chars)
`user_id`	integer	No	Associate with user (min 1)
`user_agent`	string	No	Stored on record; defaults to request User-Agent
`ip_address`	string	No	Valid IPv4/IPv6; defaults to client IP
`page_title`	string	No	Override bridge preview title (max 500)
`thumbnail_url`	string (URL)	No	Override bridge preview image
`source`	string	No	Origin label (e.g. `api`, `engagyo`). Defaults to `api`
`url_cloak`	integer	No	`1` = bridge page (default). `0` = direct 302 redirect

Example request (JSON)

cURL

curl -X POST "https://shrtnlnk.com/api/links" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "original_url": "https://example.com/blog/post",
    "user_id": 42,
    "user_agent": "MyIntegration/1.0",
    "ip_address": "203.0.113.10"
  }'

Success response

201 New link created 200 Existing link returned

JSON

{
  "success": true,
  "id": 15,
  "short_url": "https://shrtnlnk.com/s/a1B2c3",
  "short_code": "a1B2c3",
  "original_url": "https://example.com/blog/post",
  "redirect_mode": "bridge",
  "page_title": "Example Blog Post",
  "thumbnail_url": "https://example.com/og-image.jpg",
  "source": "api",
  "url_cloak": 1,
  "cloaked": true,
  "clicks": 0,
  "existing": false,
  "created_at": "2026-05-26T14:30:00+00:00"
}

Get link details (API)

Fetch a short link by its code, including the current clicks count.

GET /api/links/{code}

Path parameters

Parameter	Type	Description
`code`	string	Short link code (e.g. `abc123`)

Example

cURL

curl -X GET "https://shrtnlnk.com/api/links/abc123" \
  -H "Accept: application/json"

Success response

200 Link found

JSON

{
  "success": true,
  "id": 15,
  "short_url": "https://shrtnlnk.com/s/abc123",
  "short_code": "abc123",
  "original_url": "https://example.com/blog/post",
  "redirect_mode": "bridge",
  "bridge_delay_seconds": 0,
  "page_title": "Example Blog Post",
  "thumbnail_url": "https://example.com/og-image.jpg",
  "source": "api",
  "url_cloak": 1,
  "cloaked": true,
  "clicks": 42,
  "user_id": null,
  "created_at": "2026-05-26T14:30:00+00:00",
  "updated_at": "2026-05-26T16:05:00+00:00"
}

Not found

404

JSON

{
  "success": false,
  "message": "Short link not found."
}

Update short link (API)

Partially update an existing link by short_code. Send only the fields you want to change.

PATCH /api/links/{code}

Also accepts PUT with the same body.

Body parameters (all optional)

Parameter	Type	Description
`original_url`	string (URL)	New destination URL
`url_cloak`	integer	`1` = bridge, `0` = direct
`page_title`	string	Bridge preview title
`thumbnail_url`	string (URL)	Bridge preview image
`source`	string	Origin label
`user_id`	integer	Owner user ID

Example

cURL

curl -X PATCH "https://shrtnlnk.com/api/links/abc123" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "original_url": "https://example.com/updated",
    "url_cloak": 1,
    "page_title": "Updated title"
  }'

Success response

200 Returns the updated link (same shape as GET).

Create short link (web)

Used by the homepage. Same logic as /api/links with fewer parameters.

POST /shorten

Parameter	Required	Description
`original_url`	Yes	Destination URL
`user_agent`	No	Defaults to browser User-Agent

Browser requests must include X-CSRF-TOKEN (from the page meta tag).

Visit short link

GET /s/{code}

Returns HTML bridge page (not JSON). Increments clicks by 1. {code} is alphanumeric.

200 Bridge page 404 Unknown code

Response fields

Field	Description
`success`	`true` on success
`id`	Database ID
`short_url`	Full shareable URL
`short_code`	Code used in `/s/{code}`
`original_url`	Normalized destination
`redirect_mode`	`bridge` or `direct`
`url_cloak`	`1` (bridge) or `0` (direct)
`cloaked`	Boolean alias of `url_cloak`
`page_title`	Bridge preview title
`thumbnail_url`	Preview image URL (nullable)
`source`	Where the link was created (`web`, `api`, or custom)
`clicks`	Visit count
`user_id`	Owner user ID (nullable)
`updated_at`	Last update (ISO 8601)
`existing`	`true` on create when link already existed
`created_at`	ISO 8601 timestamp

Errors

422 Validation failed or invalid URL

Validation error

{
  "message": "The original url field must be a valid URL.",
  "errors": {
    "original_url": ["The original url field must be a valid URL."]
  }
}

Business error

{
  "success": false,
  "message": "Invalid URL"
}

Behavior notes

URL normalization

Trims whitespace and adds https:// if missing
Lowercases hostname; removes trailing slash on path

Link preview

On create, the server may fetch Open Graph tags from the destination. Failures fall back to hostname as title with no thumbnail.

Deduplication

Same original_url, source, and cloak setting returns an existing link when scoped by user_id, user_agent, or the anonymous bucket.