Developers
nLink API and webhooks
Create and manage links from your own app, pull click statistics, and receive click and link events in real time with webhooks. The API and webhooks are available on Gold and Enterprise plans.
Authentication and limits
Create your API key under Settings → API access. The key is shown once; we store only its hash. Send it with every request:
Authorization: Bearer nlk_xxxxxxxxxxxxxxxx # ya da / or X-API-Key: nlk_xxxxxxxxxxxxxxxx
- Base URL:
https://api.nlink.tr/api/v1 - Rate limit: Gold 60/min, Enterprise 300/min. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; when exceeded you get 429 with Retry-After.
- Your plan limits (monthly links) also apply to the API.
- All bodies are JSON; times are ISO 8601 (UTC).
Endpoints
GET/api/v1/me
Account, plan, limits and this month's click usage.
curl https://api.nlink.tr/api/v1/me -H "Authorization: Bearer $NLINK_API_KEY"
POST/api/v1/links
Creates a link. The destination is safety-scanned; counts against your plan quota.
| url | Destination URL (required, http/https). |
| slug | Custom short name (optional). 409 slug_taken if in use. |
| domain | nlink.tr or your configured custom domain (optional). |
curl -X POST https://api.nlink.tr/api/v1/links \
-H "Authorization: Bearer $NLINK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/yaz-indirimi", "slug": "kampanya"}'201 Created
{
"id": "6702f1c4a9b3e1d2c3f4a5b6",
"slug": "kampanya",
"short_url": "https://nlink.tr/kampanya",
"url": "https://example.com/yaz-indirimi",
"domain": "nlink.tr",
"created_at": "2026-10-03T12:00:00Z",
"created_by": null,
"clicks": 128,
"last_click_at": "2026-10-04T08:15:02Z",
"group_ids": []
}GET/api/v1/links
Your links, newest first, paginated.
| page | Page (default 1). |
| limit | Per page 1–100 (default 50). |
| q | Search in destination, short name or title. |
curl "https://api.nlink.tr/api/v1/links?page=1&limit=50" -H "Authorization: Bearer $NLINK_API_KEY"
{ "data": [ … ], "page": 1, "limit": 50, "total": 312, "has_more": true }GET/api/v1/links/{id}
A single link. {id} may be the link id or the short name.
curl https://api.nlink.tr/api/v1/links/kampanya -H "Authorization: Bearer $NLINK_API_KEY"
PATCH/api/v1/links/{id}
Changes the destination and/or short name. A new destination is re-scanned and logged in the link history.
| url | New destination URL. |
| slug | New short name. |
curl -X PATCH https://api.nlink.tr/api/v1/links/kampanya \
-H "Authorization: Bearer $NLINK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/kis-indirimi"}'DELETE/api/v1/links/{id}
Permanently deletes the link (204). The short name is never reused; visitors see a "removed" page.
curl -X DELETE https://api.nlink.tr/api/v1/links/kampanya -H "Authorization: Bearer $NLINK_API_KEY"
GET/api/v1/links/{id}/stats
Click statistics (bots excluded): daily series, country, city, device, browser, source, campaign.
| days | Number of days 1–365 (default 30). |
curl "https://api.nlink.tr/api/v1/links/kampanya/stats?days=7" -H "Authorization: Bearer $NLINK_API_KEY"
Errors
Error responses always have the same shape:
{ "error": { "code": "slug_taken", "message": "Bu kısa ad kullanımda." } }| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_slug · invalid_domain | Invalid short name or domain. |
| 401 | unauthorized · invalid_api_key | Missing or invalid key. |
| 403 | plan_required | API requires Gold or Enterprise. |
| 404 | not_found | Link not found (or not yours). |
| 409 | slug_taken · slug_reserved · slug_retired | Short name in use, reserved, or belonged to a deleted link (never reissued). |
| 422 | invalid_url · unsafe_url | Destination invalid or blocked by the safety scan. |
| 429 | rate_limited · quota_exceeded | Per-minute limit or plan quota reached. |
Webhook
Add webhook endpoints under Settings → Webhook (up to 5, https only). When a selected event happens we send a signed POST request to your endpoint.
| link.created | A link was created (dashboard, extension or API). |
| link.updated | The destination or short name changed. |
| link.deleted | A link was deleted. |
| link.clicked | A human click (bots excluded; within your monthly click allowance). Includes country, city, device, source and campaign; no IP address is sent. |
| ping | "Send test" from the dashboard. |
Example request:
POST https://ornek.com/nlink-webhook
Content-Type: application/json
X-Nlink-Event: link.clicked
X-Nlink-Delivery: 6702f9a1c2d3e4f5a6b7c8d9
X-Nlink-Signature: t=1791047318,v1=5f2b…c91e
{
"id": "6702f9a1c2d3e4f5a6b7c8d9",
"event": "link.clicked",
"created_at": "2026-10-04T08:15:02Z",
"data": {
"link": { "id": "6702f1c4…", "slug": "kampanya", "short_url": "https://nlink.tr/kampanya", "url": "https://example.com/yaz-indirimi" },
"clicked_at": "2026-10-04T08:15:02Z",
"country": "TR", "region": "İstanbul", "city": "Istanbul",
"device": "mobile", "os": "iOS", "browser": "Mobile Safari",
"referrer_host": "instagram.com", "app": "instagram", "campaign": "yaz",
"unique": true
}
}Verifying the signature
v1 in the X-Nlink-Signature header is the HMAC-SHA256 of "<t>.<raw body>" with the webhook's signing secret (whsec_…). Verify the raw body before parsing it and reject requests whose timestamp t is older than 5 minutes (replay protection).
Node.js
import crypto from "node:crypto";
// rawBody: isteğin ham gövdesi (JSON.parse ETMEDEN önce), secret: whsec_…
export function verify(rawBody, header, secret, toleranceSec = 300) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}Python
import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t = int(parts.get("t", 0))
if abs(time.time() - t) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))Delivery and retries
- Your endpoint must return 2xx within 10 seconds; redirects are not followed.
- Failed deliveries are retried after 1m, 5m, 30m, 2h, 6h and 12h. The same event may arrive more than once; deduplicate with X-Nlink-Delivery.
- After 50 consecutive failures the webhook is disabled; you can re-enable it in the dashboard, where recent deliveries and errors are listed.
- Event order is not guaranteed; use the created_at field.
Questions? [email protected]