Developers

API guide

Programmatic URL shortening with the same plan rules as the dashboard. Create API keys under /app/keys after verifying your email.

Quick start

Verify your email, create a key at /app/keys, then call the API with Bearer auth. Responses are JSON unless you download a QR image.

Authentication

Send Authorization: Bearer lnkz_… on every request. Keys are shown once at creation. Prefixes (first 8 chars) appear in the dashboard so you can tell keys apart.

Rate limits

Daily caps are per UTC day: Free 100, Pro 10,000, Business 100,000. Successful responses include X-RateLimit-Limit and X-RateLimit-Remaining. Daily quota exhaustion returns 429.

Errors

All errors use { "error": { "code": "…", "message": "…" } }. Common codes: unauthorized, invalid_url, alias_taken, reserved, gated, quota_exceeded.

Code	HTTP	Meaning
unauthorized	401	Missing or invalid API key.
invalid_url	400	Destination failed URL validation.
alias_taken	409	Custom alias already in use.
reserved	400	Alias or slug is reserved.
gated	403	Feature requires Pro or Business.
quota_exceeded	403	Monthly create quota reached.
rate_limited	429	Daily API cap reached.

Examples

Create a short link

curl -X POST https://lnkz.xyz/api/v1/links \
  -H "Authorization: Bearer lnkz_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/long-page","title":"Launch","domain":"links.example.com"}'

List links (cursor pagination)

curl "https://lnkz.xyz/api/v1/links?limit=20" \
  -H "Authorization: Bearer lnkz_YOUR_KEY"

Download QR (PNG)

curl "https://lnkz.xyz/api/v1/links/abc123/qr?format=png" \
  -H "Authorization: Bearer lnkz_YOUR_KEY" \
  --output qr.png

Notes

• Base URL: https://lnkz.xyz/api/v1 (use your NEXT_PUBLIC_APP_URL in local dev).
• Authenticate with Authorization: Bearer lnkz_… from /app/keys.
• Email must be verified before creating API keys (Google sign-in counts as verified).
• Daily limits: Free 100, Pro 10,000, Business 100,000 requests per UTC day.
• Custom aliases, QR, UTM, expiration, and link passwords require Pro+. Custom domains and teams require Business.
• Monthly link create quotas match your plan - same as the dashboard.
• tags is an array of up to 8 lowercase labels. expiresAt is ISO-8601. password is stored hashed; send null to clear.

Endpoints

POST/api/v1/links

Create a short link. Same validation and plan gates as the dashboard.

Request

{ "url": "https://example.com", "title": "optional", "alias": "optional", "tags": ["launch"], "expiresAt": "2026-12-31T23:59:00.000Z", "password": "optional", "utm": { "source": "", "medium": "", "campaign": "", "term": "", "content": "" } }

Response

{ "code": "k9Qx2mP", "shortUrl": "https://lnkz.xyz/k9Qx2mP", "destinationUrl": "https://example.com" }

GET/api/v1/links

List your links with cursor pagination.

Request

Query: ?cursor={linkId}&limit=20 (max 100)

Response

{ "data": […], "nextCursor": "uuid-or-null" }

GET/api/v1/links/{code}

Fetch one link by code.

Response

{ "code": "…", "destinationUrl": "…", "title": "…", "clickCount": "42" }

PATCH/api/v1/links/{code}

Update title or destination URL.

Request

{ "title": "New label", "url": "https://example.com/new", "tags": ["launch"], "expiresAt": null, "password": null, "archived": false }

Response

{ "code": "…", "destinationUrl": "…", "title": "…" }

DELETE/api/v1/links/{code}

Soft delete. The code is never reused.

Response

{ "ok": true }

GET/api/v1/links/{code}/qr

Download QR as PNG or SVG. Requires Pro+.

Request

Query: ?format=png|svg

Response

Binary image (Content-Type: image/png or image/svg+xml)

Need help? See the help center.