API Documentation

Use the Lynkd REST API to create, manage, and track short links programmatically. All endpoints require an API key passed in the Authorization header.

Contents

Authentication Links Analytics QR Codes A/B Testing Retargeting Pixels Smart Routing Webhooks Rate Limits

Authentication

All API requests require a Bearer token. Generate your API key in the Lynkd dashboard under Settings > API Keys.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://lynkd.co/api/links

Base URL: https://lynkd.co

Links

POST/api/links

Create a new short link. Optionally specify a custom slug, UTM parameters, expiration, and title.

Request Body

{
  "url": "https://example.com/landing-page",
  "slug": "spring-sale",
  "title": "Spring Campaign",
  "utm_source": "instagram",
  "utm_medium": "social",
  "utm_campaign": "spring-2026",
  "expires_at": "2026-04-01T00:00:00Z"
}

Response

{
  "success": true,
  "data": {
    "id": "abc-123",
    "shortCode": "spring-sale",
    "originalUrl": "https://example.com/landing-page",
    "totalClicks": 0,
    "isActive": true,
    "createdAt": "2026-03-01T12:00:00Z"
  }
}

GET/api/links

List all links in your workspace. Supports search, pagination (limit/offset), and sorting.

Response

{
  "success": true,
  "data": [
    {
      "id": "abc-123",
      "shortCode": "spring-sale",
      "originalUrl": "https://example.com/landing-page",
      "totalClicks": 1842,
      "isActive": true,
      "createdAt": "2026-03-01T12:00:00Z"
    }
  ]
}

PUT/api/links/:id

Update a link's properties: URL, title, UTM params, active status, or expiration.

Request Body

{
  "url": "https://example.com/new-page",
  "active": true
}

Response

{
  "success": true,
  "data": { "id": "abc-123", "originalUrl": "https://example.com/new-page" }
}

DELETE/api/links/:id

Permanently delete a link. Existing short URLs will return 404 after deletion.

Response

{
  "success": true,
  "data": { "deleted": true }
}

Analytics

GET/api/analytics?linkId=:id

Retrieve click analytics for a link. Returns geographic, device, browser, OS, and referrer breakdowns along with daily click trends.

Response

{
  "success": true,
  "data": {
    "totalClicks": 1842,
    "clicksByCountry": { "US": 892, "GB": 341 },
    "clicksByDevice": { "mobile": 1105, "desktop": 624 },
    "clicksByBrowser": { "Chrome": 812, "Safari": 534 },
    "clicksByDay": [
      { "date": "2026-03-01", "clicks": 142 }
    ]
  }
}

QR Codes

POST/api/qr

Generate a QR code data URL for a link. Supports custom colors, size, and optional logo overlay.

Request Body

{
  "linkId": "abc-123",
  "size": 512,
  "fgColor": "#ffffff",
  "bgColor": "#0a0a0f",
  "logoUrl": "https://example.com/logo.png"
}

Response

{
  "success": true,
  "data": {
    "dataUrl": "data:image/png;base64,...",
    "linkId": "abc-123"
  }
}

GET/api/qr?linkId=:id&size=256

Download a QR code as a PNG image. Returns binary image data with Content-Type: image/png.

Response

Binary PNG image (Content-Type: image/png)

A/B Testing

Split traffic between two URLs and compare performance. Available on Agency plan and above.

POST/api/links/:id/ab-test

Create an A/B test for a link. Traffic will be split between the original URL (variant A) and the specified variant B URL.

Request Body

{
  "variantBUrl": "https://example.com/variant-b",
  "splitPercent": 50
}

Response

{
  "success": true,
  "data": {
    "id": "test-456",
    "linkId": "abc-123",
    "variantBUrl": "https://example.com/variant-b",
    "splitPercent": 50,
    "status": "active"
  }
}

GET/api/links/:id/ab-test

Fetch the A/B test configuration and results (click counts per variant) for a link.

Response

{
  "success": true,
  "data": {
    "test": {
      "id": "test-456",
      "variantBUrl": "https://example.com/variant-b",
      "splitPercent": 50,
      "status": "active"
    },
    "results": { "A": 923, "B": 919 }
  }
}

DELETE/api/links/:id/ab-test

Remove the A/B test from a link. Click data is preserved for historical analysis.

Response

{
  "success": true,
  "data": { "deleted": true }
}

Retargeting Pixels

Attach Facebook, Google, TikTok, or custom tracking pixels to links. Available on Growth plan and above.

POST/api/settings/pixels

Create a new retargeting pixel. Supported platforms: facebook, google, tiktok, custom.

Request Body

{
  "platform": "facebook",
  "pixelId": "123456789",
  "name": "Meta Ads Pixel"
}

Response

{
  "success": true,
  "data": {
    "id": "px-789",
    "platform": "facebook",
    "pixelId": "123456789",
    "name": "Meta Ads Pixel"
  }
}

POST/api/links/:id/pixels

Attach a pixel to a link. When the link is clicked, the pixel fires before redirecting.

Request Body

{
  "pixelId": "px-789"
}

Response

{
  "success": true,
  "data": { "attached": true }
}

Smart Routing Rules

Route visitors to different URLs based on country or device type. Available on Agency plan and above.

POST/api/links/:id/rules

Add a geo-targeting or device-routing rule. Rules are evaluated in priority order (lower number = higher priority).

Request Body

{
  "type": "geo",
  "condition": "US",
  "destinationUrl": "https://example.com/us-page",
  "priority": 0
}

Response

{
  "success": true,
  "data": {
    "id": "rule-101",
    "type": "geo",
    "condition": "US",
    "destinationUrl": "https://example.com/us-page",
    "priority": 0
  }
}

GET/api/links/:id/rules

List all routing rules for a link, ordered by priority.

Response

{
  "success": true,
  "data": [
    {
      "id": "rule-101",
      "type": "geo",
      "condition": "US",
      "destinationUrl": "https://example.com/us-page",
      "priority": 0
    },
    {
      "id": "rule-102",
      "type": "device",
      "condition": "MOBILE",
      "destinationUrl": "https://m.example.com",
      "priority": 1
    }
  ]
}

Webhooks

Register HTTP endpoints to receive real-time events. Each request includes an X-Lynkd-Signature header (HMAC-SHA256) for verification.

POST/api/settings/webhooks

Create a webhook endpoint. Events: link.clicked, link.created, link.deleted, link.milestone.

Request Body

{
  "url": "https://your-server.com/webhooks/lynkd",
  "events": ["link.clicked", "link.created"],
  "description": "Production webhook"
}

Response

{
  "success": true,
  "data": {
    "id": "wh-001",
    "url": "https://your-server.com/webhooks/lynkd",
    "secret": "a1b2c3...",
    "events": "link.clicked,link.created",
    "isActive": true
  }
}

Webhook Payload Format

{
  "event": "link.clicked",
  "timestamp": "2026-03-06T12:00:00.000Z",
  "data": {
    "linkId": "abc-123",
    "shortCode": "spring-sale",
    "country": "US",
    "device": "mobile",
    "browser": "Chrome"
  }
}

Verify the signature: compute HMAC-SHA256 of the raw body using your endpoint secret and compare to the X-Lynkd-Signature header value.

Rate Limits

Plan	Requests / minute	Requests / day
Free	60	1,000
Pro	300	10,000
Agency	600	50,000
Enterprise	1,000	100,000

Error Codes

Code	Meaning
400	Bad request — invalid or missing parameters
401	Unauthorized — invalid or missing API key
403	Forbidden — feature not available on your plan
404	Not found — resource does not exist
429	Rate limited — too many requests
500	Internal server error

All errors return a JSON body: {"success": false, "error": "message"}