API documentation
A REST API to create short links and read analytics. Easy to integrate from any language — just send your API key.
Quick start
- Sign up and open the API keys section in your dashboard.
- Create a key and copy it (shown only once).
- Send the key in the header
Authorization.
curl -X POST https://link.tj/api/v1/links \
-H "Authorization: Bearer lnktj_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/a/very/long/link"}'Authentication
Every request must include the header Authorization: Bearer <key> (or X-Api-Key: <key>). Base URL:
https://link.tj/api/v1Keys are tied to your account, so the same plan limits apply as in the UI. CORS is open (*); the API can be called from the browser.
Conditions & requirements
- You need a link.tj account and a created API key (the “API keys” section).
- The key is shown once — copy it right away.
- Send the header Authorization: Bearer <key> or X-Api-Key: <key>.
- Your plan limits apply.
- Rate limit: 120 requests per minute per key (otherwise 429 with retryAfter).
- CORS is open (*) — the API can be called from the browser.
App authentication (mobile)
Mobile and native apps obtain a token with email and password: POST /api/auth/token. The response contains a JWT that you pass to /api/v1/* exactly like an API key: Authorization: Bearer <token>. If 2FA is enabled, include a code field; without it the endpoint returns 401 with error: needs_2fa.
/api/auth/tokenEmail/password login → JWT for /api/v1/*. Body: email, password, code? (for 2FA).
How to use: Send email and password to obtain a JWT for the app.
curl -X POST https://link.tj/api/auth/token \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com","password":"••••••••"}'Response
{
"token": "eyJhbGciOi...",
"user": { "id": "clx...", "email": "you@example.com", "name": "You", "role": "USER" }
}Conditions & requirements
- email and password are required (otherwise 400).
- The account must not be blocked (otherwise 403).
- If 2FA is enabled, add a code field; without it 401 with error: needs_2fa.
- Limit: 30 attempts per 15 min per IP and 10 per email (otherwise 429).
- Pass the returned JWT to /api/v1/* as Authorization: Bearer <token>.
Endpoints
/api/v1/meAccount, plan and monthly usage.
How to use: Request your profile, plan and current-month usage.
curl https://link.tj/api/v1/me \
-H "Authorization: Bearer lnktj_API_KEY"Response
{
"data": {
"email": "you@example.com",
"plan": { "name": "Free", "linkLimit": 5 },
"usage": { "linksUsed": 2, "linksRemaining": 3, "clicksUsed": 87 }
}
}Conditions & requirements
- A valid API key or JWT is required.
- The account must not be blocked.
- GET only — data belongs to the key owner.
/api/v1/linksCreate a short link. Fields: url (required for kind=url), slug (optional), title (optional), kind (optional: url | wifi | vcard | text), payload (object for non-url kinds).
wifi/vcard/text kinds require a paid plan (otherwise 403). Such a QR points to a tracked page /l/{slug}.
How to use: Send JSON with a url field (classic link) or kind + payload (typed link).
curl -X POST https://link.tj/api/v1/links \
-H "Authorization: Bearer lnktj_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com","slug":"promo","title":"Promo"}'Example: Wi-Fi (paid plan)
curl -X POST https://link.tj/api/v1/links \
-H "Authorization: Bearer lnktj_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind":"wifi","title":"Guest Wi-Fi","payload":{"ssid":"MyNet","encryption":"WPA","password":"secret123"}}'Response 201
{
"data": {
"id": "clx...",
"slug": "promo",
"shortUrl": "https://link.tj/promo",
"kind": "url",
"originalUrl": "https://example.com",
"summary": null,
"clicks": 0
},
"usage": { "linksUsed": 3, "linkLimit": 5, "linksRemaining": 2 }
}Response 402 — plan limit reached
{
"error": "limit_reached",
"code": "limit_reached",
"recommend": { "name": "Core", "priceMonthly": 8, "linkLimit": 100 }
}Conditions & requirements
- url is required and must be a valid http(s) URL when kind=url (otherwise 400).
- slug is optional; if taken → 409, if empty it is generated automatically.
- kind: url | wifi | vcard | text (default url).
- wifi/vcard/text types require a paid plan (otherwise 403) and a payload field.
- title is optional, max 200 characters.
- When the plan link limit is reached you get 402 with a recommended plan.
- An X-Client: telegram | mobile header tags the link's creation source (default api) — visible in source analytics.
- On the Free plan, exhausting the monthly limit triggers an upgrade nudge (in-app, Telegram and SMS); you can upgrade right away without waiting for the month to reset.
/api/v1/linksA list of your links. Parameters: limit (1–100), offset.
How to use: Fetch your links with pagination.
curl "https://link.tj/api/v1/links?limit=20&offset=0" \
-H "Authorization: Bearer lnktj_API_KEY"Response — list
{
"total": 42,
"limit": 20,
"offset": 0,
"data": [
{ "id": "clx...", "slug": "promo", "shortUrl": "https://link.tj/promo", "kind": "url",
"originalUrl": "https://example.com", "clicks": 128, "isActive": true }
]
}Conditions & requirements
- limit from 1 to 100 (default 50).
- offset ≥ 0 for pagination.
- Only the key owner’s links are returned; the total field is the overall count.
/api/v1/links/{id_or_slug}Link details and click analytics (by country, device, source).
How to use: Pass a link id or slug to get its details and click analytics.
curl https://link.tj/api/v1/links/promo \
-H "Authorization: Bearer lnktj_API_KEY"Response — details & analytics
{
"data": {
"id": "clx...", "slug": "promo", "shortUrl": "https://link.tj/promo",
"originalUrl": "https://example.com", "clicks": 128, "isActive": true,
"analytics": {
"byCountry": [ { "name": "TJ", "count": 80 }, { "name": "RU", "count": 48 } ],
"byDevice": [ { "name": "mobile", "count": 95 }, { "name": "desktop", "count": 33 } ],
"byReferrer": [ { "name": "t.me", "count": 60 }, { "name": "Unknown", "count": 68 } ]
}
}
}Conditions & requirements
- Either an id or a slug is accepted.
- The link must belong to the key owner (otherwise 404).
- The response includes an analytics block: by country, device and referrer.
/api/v1/links/{id_or_slug}Update a link: active state (isActive) and folder (folderId).
How to use: Pass an id or slug and only the fields you want to change.
curl -X PATCH https://link.tj/api/v1/links/promo \
-H "Authorization: Bearer lnktj_API_KEY" \
-H "Content-Type: application/json" \
-d '{"isActive":false}'Response
{
"data": { "id": "clx...", "slug": "promo", "title": "Promo", "isActive": false, "folderId": null }
}Conditions & requirements
- The link must belong to the key owner (otherwise 404).
- isActive (boolean) — enables or disables redirecting the link.
- folderId (string | null) — move the link into a folder or out of one.
- The response returns the updated object: id, slug, title, isActive, folderId.
/api/v1/links/{id_or_slug}Delete a link and its analytics.
How to use: Pass an id or slug to delete the link.
curl -X DELETE https://link.tj/api/v1/links/promo \
-H "Authorization: Bearer lnktj_API_KEY"Conditions & requirements
- The link must belong to the key owner (otherwise 404).
- The delete is soft: the link is deactivated and moved to the “Deleted” section; its analytics are kept.
- Until the current period ends the link still counts toward the plan's monthly limit (quota-bypass protection).
Webhooks (outbound events)
Register a URL in the “Webhooks” section of your dashboard — we POST to your server when an event fires. Body: { event, data, ts }. Headers: X-LinkTJ-Event and X-LinkTJ-Signature.
How to use: Add a URL and subscribe to events in the “Webhooks” section, then verify the signature on your server.
Events
link.created— link.created — a short link was created. data: { id, slug, url }.subscription.created— subscription.created — a subscription was started or renewed. data: { plan, amount, interval }.
POST https://your-server.example/webhook
X-LinkTJ-Event: link.created
X-LinkTJ-Signature: <hmac-sha256-hex>
Content-Type: application/json
{ "event": "link.created", "data": { "id": "clx...", "slug": "promo", "url": "https://example.com" }, "ts": "2026-01-01T12:00:00.000Z" }The X-LinkTJ-Signature header is an HMAC-SHA256 of the raw request body signed with your webhook secret (whsec_…). Compare it to verify the request really came from link.tj.
Conditions & requirements
- The URL must be public https — internal and local addresses are rejected (SSRF protection).
- Subscribe to at least one event (link.created, subscription.created).
- Verify X-LinkTJ-Signature = HMAC-SHA256(request body, secret whsec_…).
- The host is re-checked on delivery (DNS-rebinding protection); redirects are not followed.
- Delivery timeout is 5 seconds; respond with a 2xx code.
Scheduled jobs (cron)
An external scheduler can trigger subscription renewals and weekly reports by passing the secret: ?secret=<CRON_SECRET>. The task parameter accepts renew, weekly or all (default all).
How to use: Point an external scheduler at the endpoint with the secret.
/api/cron?secret=&task=renew|weekly|allcurl -X POST "https://link.tj/api/cron?secret=CRON_SECRET&task=renew"Conditions & requirements
- Pass ?secret=<CRON_SECRET> (or call it from a superadmin session).
- task: renew | weekly | all (default all).
- Method GET or POST.
Status codes
| 200 / 201 | Success |
| 400 | Bad request (e.g. invalid URL or slug) |
| 401 | Missing or invalid API key |
| 402 | Plan limit reached — upgrade required |
| 403 | Forbidden (e.g. wifi/vcard/text link types on the Free plan) |
| 404 | Link not found |
| 409 | Slug already taken |
| 429 | Too many requests — rate limit hit |