Short URLs API

The Short URLs API lets you create and manage branded short links under your Nodukan domain (e.g., ndk.in/my-slug). Every click is tracked with geo, referrer, and device data.

Endpoints#

Method	Path	Scope	Description
GET	/short-urls	short_urls:read	List all short URLs
POST	/short-urls	short_urls:write	Create a short URL
GET	/short-urls/:slug	short_urls:read	Get a short URL with analytics

---

GET /short-urls#

Returns a paginated list of all short URLs for the account.

Query parameters#

Parameter	Type	Description
limit	integer	Max records (default 20, max 100)
offset	integer	Records to skip

curl "https://api.nodukan.com/v1/short-urls?limit=20" \
  -H "Authorization: Bearer NDK_live_..."

const res = await fetch('https://api.nodukan.com/v1/short-urls', {
  headers: { Authorization: `Bearer ${process.env.NODUKAN_API_KEY}` },
});
const { data, pagination } = await res.json();

Response#

{
  "data": [
    {
      "id": "url_01j9x4km2v",
      "slug": "notion-template",
      "shortUrl": "https://ndk.in/notion-template",
      "destinationUrl": "https://priyasharma.nodukan.com/lead-magnets/free-notion-template",
      "title": "Notion Template Lead Magnet",
      "clicks": 2340,
      "uniqueClicks": 1987,
      "isActive": true,
      "createdAt": "2025-11-10T08:00:00Z"
    },
    {
      "id": "url_01j9y7mp3k",
      "slug": "ig-captions",
      "shortUrl": "https://ndk.in/ig-captions",
      "destinationUrl": "https://priyasharma.nodukan.com/products/instagram-caption-pack",
      "clicks": 890,
      "uniqueClicks": 763,
      "isActive": true,
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": { "total": 18, "limit": 20, "offset": 0, "hasMore": false },
  "requestId": "req_01j9xabc..."
}

---

POST /short-urls#

Creates a new short URL. The slug must be unique across the platform.

Request body#

Field	Type	Required	Description
destinationUrl	string (URL)	✅	The full URL to redirect to
slug	string	No	Custom slug (alphanumeric + hyphens). Omit for auto-generated slug.
title	string	No	Internal label for the link (not shown publicly)
utmSource	string	No	Auto-append utm_source to the destination URL
utmMedium	string	No	Auto-append utm_medium
utmCampaign	string	No	Auto-append utm_campaign
expiresAt	ISO datetime	No	Optional expiry. Link returns 410 Gone after this date.
passwordProtected	boolean	No	Require a password to access the destination
password	string	Conditional	Required if passwordProtected: true

curl -X POST https://api.nodukan.com/v1/short-urls \
  -H "Authorization: Bearer NDK_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://priyasharma.nodukan.com/lead-magnets/free-notion-template",
    "slug": "notion-template",
    "title": "Notion Template Lead Magnet",
    "utmSource": "instagram",
    "utmMedium": "bio"
  }'

const res = await fetch('https://api.nodukan.com/v1/short-urls', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NODUKAN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    destinationUrl: 'https://priyasharma.nodukan.com/lead-magnets/free-notion-template',
    slug: 'notion-template',
    title: 'Notion Template — May 2026 Campaign',
    utmSource: 'instagram',
    utmMedium: 'bio',
    utmCampaign: 'may-launch',
  }),
});

const { data } = await res.json();
console.log('Short URL:', data.shortUrl);

Response 201 Created#

{
  "data": {
    "id": "url_01j9znew00",
    "slug": "notion-template",
    "shortUrl": "https://ndk.in/notion-template",
    "destinationUrl": "https://priyasharma.nodukan.com/lead-magnets/free-notion-template",
    "title": "Notion Template — May 2026 Campaign",
    "clicks": 0,
    "uniqueClicks": 0,
    "isActive": true,
    "utmParams": {
      "source": "instagram",
      "medium": "bio",
      "campaign": "may-launch"
    },
    "createdAt": "2026-05-06T11:00:00Z"
  },
  "requestId": "req_01j9xabc..."
}

If the slug is already taken, you'll receive a 409 already_exists error.

---

GET /short-urls/:slug#

Returns a single short URL with detailed click analytics.

curl https://api.nodukan.com/v1/short-urls/notion-template \
  -H "Authorization: Bearer NDK_live_..."

const res = await fetch('https://api.nodukan.com/v1/short-urls/notion-template', {
  headers: { Authorization: `Bearer ${process.env.NODUKAN_API_KEY}` },
});
const { data } = await res.json();
console.log('Total clicks:', data.analytics.totalClicks);

Response#

{
  "data": {
    "id": "url_01j9x4km2v",
    "slug": "notion-template",
    "shortUrl": "https://ndk.in/notion-template",
    "destinationUrl": "https://priyasharma.nodukan.com/lead-magnets/free-notion-template",
    "title": "Notion Template Lead Magnet",
    "isActive": true,
    "analytics": {
      "totalClicks": 2340,
      "uniqueClicks": 1987,
      "clicksByCountry": {
        "IN": 1820,
        "US": 210,
        "GB": 95,
        "AE": 72,
        "SG": 48
      },
      "clicksByDevice": {
        "mobile": 1760,
        "desktop": 510,
        "tablet": 70
      },
      "clicksByReferrer": {
        "instagram.com": 980,
        "direct": 670,
        "linkedin.com": 340,
        "t.co": 180
      },
      "clicksLast7Days": 340,
      "clicksLast30Days": 1240
    },
    "createdAt": "2025-11-10T08:00:00Z",
    "updatedAt": "2026-05-06T10:45:00Z"
  },
  "requestId": "req_01j9xabc..."
}