Developer API

Create and manage short links programmatically over a REST API (server-to-server). Generate a key in the dashboard → Developer API. 1,000 free calls per month.

Authentication

Each request carries Authorization: Bearer lk_live_…. Responses include X-RateLimit-Remaining; when the quota is used up you get 429.

Create a short link

POST /api/v1/links

curl -X POST https://link.luvai.net/api/v1/links \
  -H "Authorization: Bearer lk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://example.com.tw/sale",
    "slug": "summer",
    "title": "Summer sale",
    "escape_inapp": true,
    "utm": { "source": "ig", "medium": "bio" }
  }'

# 201 -> { "ok": true, "id": 42, "slug": "summer",
#          "short_url": "https://link.luvai.net/summer" }

Fields: target_url (required), slug (blank = random), title, mode (simple｜ab｜device｜geo), variants, redirect_type (301｜302), og{title,description,image}, pixel_fb／ga／gtm／tiktok／line, escape_inapp, expires_at (ISO), max_clicks (click cap, 0 = unlimited), utm, password. Destinations are auto-scanned for phishing/malware.

List / get / delete

curl https://link.luvai.net/api/v1/links?limit=50 \
  -H "Authorization: Bearer lk_live_YOUR_KEY"

curl https://link.luvai.net/api/v1/links/42 \
  -H "Authorization: Bearer lk_live_YOUR_KEY"

curl -X DELETE https://link.luvai.net/api/v1/links/42 \
  -H "Authorization: Bearer lk_live_YOUR_KEY"

Error codes

401 key missing/invalid/revoked · 403 link cap exceeded · 404 not found (or not your link) · 409 slug taken/reserved · 429 monthly quota used up · 400 bad params (incl. destination failing the safety scan).

Webhooks

Add a receiving URL in the dashboard's Webhooks panel and pick events (click / link.created). When an event fires we POST JSON to your endpoint with an HMAC-SHA256 signature in the X-Lz-Signature header (value = sha256=<hex>, computed over the entire raw body with the whsec_ secret shown once at creation). Recompute and compare it to verify the source.

POST https://your-endpoint/webhook
X-Lz-Event: click
X-Lz-Signature: sha256=<hex>

{
  "event": "click",
  "sent_at": "2026-06-21T08:00:00.000Z",
  "data": {
    "slug": "abc123", "suffix": "ig", "target": "https://...",
    "country": "TW", "device": "mobile", "os": "iOS", "referrer": "https://..."
  }
}

// verify (Node):
const h = crypto.createHmac("sha256", WHSEC).update(rawBody).digest("hex");
if (("sha256=" + h) !== req.headers["x-lz-signature"]) reject();

Conversion tracking (attribution)

Drop the snippet below on your checkout / thank-you page. When a visitor converts it reports one conversion (with optional revenue), and your stats show clicks → conversions → revenue and conversion rate. The same visitor counts once per 10 minutes. Conversion reports are a paid-plan feature.

<!-- 像素版（最簡單，貼成交頁）value／currency／suffix 皆選填 -->
<!-- suffix=管道標籤（與點擊 /suffix 同），帶了就能看「哪個管道帶來成交」 -->
<img src="https://link.luvai.net/api/conv?slug=YOUR_SLUG&value=99&currency=TWD&suffix=ig"
     width="1" height="1" style="display:none" alt="">

<!-- 或 JS 版（動態帶入訂單金額） -->
fetch("https://link.luvai.net/api/conv", {
  method: "POST", headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ slug: "YOUR_SLUG", value: 99, currency: "TWD", suffix: "ig" })
});

← Back to dashboard