REST endpoints & OpenAPI

The Edge service exposes public REST endpoints for short-link creation, resolution, analytics claims, and health checks. Explore them via Swagger UI or download the OpenAPI document for client generation.

Live specification

OpenAPI JSON — Download
Swagger UI — View interactive docs

(If you host LinkMe yourself, serve apps/edge/openapi.json behind your own domain.)

Interactive Swagger testing

Drop your App ID and App Key into the credential helper at the top of the Swagger page. They stay inside your browser and are reused for every Try it out request.
Use read-only keys for link resolution / deferred claim endpoints. Supply a server token if you want to demo POST /s or other admin routes.
Clicking Clear stored credentials wipes the local storage copy instantly.

Key endpoints

Method & path	Description
`POST /s`	Create a short link (used by the marketing site’s short-link builder).
`GET /:slug`	Resolve a link, performing platform detection/redirect.
`GET /d/:slug`	Hosted fallback landing page for each link.
`GET /qr/:slug`	Return a QR code (SVG/PNG) tied to the link.
`GET /api/deeplink?cid=...`	Claim the full payload for a given click token.
`POST /api/deferred/claim`	Fingerprint-based claim when no token is available.
`GET /api/health`	Lightweight health probe.

Link resolution behavior

All redirect behavior is captured in the OpenAPI spec, but the highlights are:

GET /:slug
- Detects platform from User-Agent and computes destination:
  - iOS: ios_custom_url → ios_store_url → deep link (https://host/<deep_link_path>)
  - Android: android_custom_url → android_store_url → deep link
  - Desktop: web_fallback_url or app-level web_fallback_url, else /d/:slug
- force_redirect_web pushes all traffic to the web fallback when present.
- UTM handling: allow_param_passthrough=1 treats stored utm_* fields as defaults. Keys flagged in utm_override prefer incoming query parameters.
- Crawler UAs receive a lightweight OpenGraph HTML response unless debug mode is requested.
- Injects cid into custom URL schemes; Play Store deep links include referrer=cid%3D... so Install Referrer can recover the click.
- Every hit records analytics and issues a 302 redirect. Append + (/:slug+) for a debug page showing computed targets without redirecting.
GET /d/:slug
- Hosted download landing page with App Store / Play buttons plus a QR code pointing at the canonical slug.
GET /qr/:slug
- Returns PNG when Accept includes image/png, otherwise SVG. Cache headers mirror the slug’s TTL.

Campaign chaining example

Create a marketing slug (e.g. fb-easter) with force_redirect_web=1, allow_param_passthrough=1, and a web_fallback_url pointing at https://foo.com/easter. Store baseline UTM values (utm_source=fb, utm_medium=social, utm_campaign=easter).
Place a download button on foo.com/easter that links to a second li-nk.me slug (e.g. download-easter) configured for deferred deep linking to the stores/apps. Leave allow_param_passthrough=1 so it merges the original UTM set with additional landing-specific keys (e.g. utm_medium=web, utm_content=landing).
When a visitor arrives through the campaign slug, they retain the Facebook UTM payload on the landing page. Clicking the download button propagates the original attribution and augments it with the landing metadata for downstream analytics.

Client generation

Use the OpenAPI doc to generate REST clients:

npx openapi-typescript https://li-nk.me/docs/api/openapi.json -o edge.d.ts

npx openapi-generator-cli generate \
  -i https://li-nk.me/docs/api/openapi.json \
  -g typescript-fetch \
  -o ./generated/edge

Regenerate whenever the portal announces new endpoints in the changelog.

For secure MCP integrations that consume these endpoints, see MCP Security & Access Model.

Appearance