Public Beta

Build with BlinkURLs

Integrate blazing fast link shortening, tracking, and analytics directly into your own applications with our REST API.

Authentication

All API requests require authentication using a Bearer token. You can generate an API key from your account settings.

Include the key in the Authorization header of your HTTP requests. Keep your keys secure and do not expose them in client-side code.

cURL Example

curl -X GET "https://blinkurls.com/api/v1/links" \
  -H "Authorization: Bearer blk_your_api_key_here" \
  -H "Content-Type: application/json"

Endpoints

POST

/api/v1/links

Create a new short link programmatically.

Request Payload

{
  "originalUrl": "https://example.com/very/long/path",
  "title": "Summer Campaign", // Optional
  "shortCode": "myBrand", // Optional custom alias
  "domainId": "cuid_here", // Optional custom domain
  "expiresAt": "2026-12-31T00:00:00Z", // Optional ISO date
  "maxClicks": 1000, // Optional click cap
  "iosUrl": "https://apps.apple.com/app/id123", // Optional iOS redirect
  "androidUrl": "https://play.google.com/store/apps/details?id=app", // Optional Android redirect
  "utmCampaign": "summer_sale" // Optional UTM tag
}

JSON Response

{
  "data": {
    "id": 1042,
    "shortCode": "myBrand",
    "originalUrl": "https://example.com...",
    "title": "Summer Campaign",
    "createdAt": "2026-07-22T12:00:00Z"
  }
}

GET

/api/v1/links

List your active short links with pagination.

Request Payload

// Query Params
?page=1&limit=50

JSON Response

{
  "data": [
    {
      "id": 1042,
      "shortCode": "myBrand",
      "originalUrl": "https://example.com...",
      "clicksCount": 142
    }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "limit": 50,
    "totalPages": 1
  }
}

GET

/api/v1/links/:id

Retrieve complete details for a specific short link by ID.

JSON Response

{
  "data": {
    "id": 1042,
    "shortCode": "myBrand",
    "originalUrl": "https://example.com...",
    "title": "Summer Campaign",
    "clicksCount": 142,
    "isActive": true
  }
}

PATCH

/api/v1/links/:id

Update destination URL, title, expiration date, or settings of an existing link.

Request Payload

{
  "originalUrl": "https://example.com/new-path",
  "title": "Updated Campaign Title",
  "isActive": true
}

JSON Response

{
  "data": {
    "id": 1042,
    "shortCode": "myBrand",
    "originalUrl": "https://example.com/new-path",
    "title": "Updated Campaign Title"
  }
}

DELETE

/api/v1/links/:id

Permanently delete a short link and its settings.

JSON Response

{
  "message": "Link deleted successfully"
}

GET

/api/v1/links/:id/stats

Retrieve click analytics and conversion stats for a specific link.

JSON Response

{
  "data": {
    "totalClicks": 1450,
    "conversions": 12,
    "totalRevenue": 450.00,
    "conversionRate": 0.83,
    "revenuePerClick": 0.31,
    "clicksByPlatform": {
      "mobile": 920,
      "desktop": 480,
      "tablet": 40,
      "unknown": 10
    },
    "clicksByDevice": {
      "mobile": 920,
      "desktop": 480,
      "tablet": 40,
      "unknown": 10
    },
    "clicksBySocialPlatform": {
      "instagram": 620,
      "x": 410,
      "linkedin": 210,
      "facebook": 110,
      "threads": 40,
      "tiktok": 20,
      "youtube": 10,
      "pinterest": 0,
      "reddit": 0,
      "bluesky": 0,
      "other": 20,
      "direct": 10
    },
    "recentClicks": [
      {
        "createdAt": "2026-07-22T12:05:00Z",
        "country": "US",
        "device": "mobile",
        "browser": "Safari",
        "referer": "https://l.instagram.com/",
        "utmSource": "instagram",
        "utmMedium": "bio_link",
        "utmCampaign": "summer26"
      }
    ]
  }
}

POST

/api/v1/links/bulk

Batch create up to 50 short links in a single request. Returns HTTP 207 Multi-Status with per-item status and errors. Requires Social plan or higher.

Request Payload

{
  "links": [
    {
      "originalUrl": "https://example.com/blog/article-1",
      "title": "Article 1",
      "utmCampaign": "newsletter_spring"
    },
    {
      "originalUrl": "https://example.com/products/widget-2",
      "shortCode": "spring-widget",
      "domainId": "cuid_here"
    }
  ]
}

JSON Response

// HTTP/1.1 207 Multi-Status
{
  "data": [
    {
      "id": 1043,
      "shortCode": "k9xP2a",
      "originalUrl": "https://example.com/blog/article-1",
      "title": "Article 1",
      "utmCampaign": "newsletter_spring",
      "createdAt": "2026-09-12T12:00:00Z"
    },
    {
      "id": 1044,
      "shortCode": "spring-widget",
      "originalUrl": "https://example.com/products/widget-2",
      "createdAt": "2026-09-12T12:00:00Z"
    }
  ],
  "errors": [],
  "meta": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  }
}

GET

/api/v1/domains

List custom and branded domains configured on your account or workspace, including verification status and default domain.

JSON Response

{
  "data": [
    {
      "id": "dom_cl9x82...",
      "domain": "links.mybrand.com",
      "verified": true,
      "isDefault": true,
      "createdAt": "2026-08-15T08:30:00Z"
    },
    {
      "id": "dom_cl9x83...",
      "domain": "go.campaign.co",
      "verified": false,
      "isDefault": false,
      "createdAt": "2026-09-01T14:15:00Z"
    }
  ]
}

GET

/api/v1/analytics

Retrieve account-wide aggregated click analytics, daily time series, device breakdowns, and top-performing links. Cached for 5 minutes.

Request Payload

// Query Params (default: last 30 days, max 365 days)
?from=2026-08-12&to=2026-09-12

JSON Response

{
  "data": {
    "totalClicks": 12850,
    "clicksByDay": [
      { "date": "2026-09-10", "clicks": 412 },
      { "date": "2026-09-11", "clicks": 589 },
      { "date": "2026-09-12", "clicks": 634 }
    ],
    "topLinks": [
      {
        "id": 1042,
        "shortCode": "myBrand",
        "originalUrl": "https://example.com/summer-sale",
        "clicks": 3420
      },
      {
        "id": 1043,
        "shortCode": "launch26",
        "originalUrl": "https://example.com/product-launch",
        "clicks": 1890
      }
    ],
    "clicksByPlatform": {
      "mobile": 7200,
      "desktop": 4850,
      "tablet": 650,
      "unknown": 150
    },
    "clicksByDevice": {
      "mobile": 7200,
      "desktop": 4850,
      "tablet": 650,
      "unknown": 150
    },
    "clicksBySocialPlatform": {
      "instagram": 4200,
      "x": 3100,
      "linkedin": 2400,
      "facebook": 1200,
      "threads": 450,
      "youtube": 300,
      "tiktok": 150,
      "pinterest": 50,
      "reddit": 40,
      "bluesky": 20,
      "other": 740,
      "direct": 200
    }
  },
  "meta": {
    "from": "2026-08-12",
    "to": "2026-09-12",
    "cachedAt": "2026-09-12T15:00:00.000Z"
  }
}

Webhooks

Webhooks allow you to build real-time integrations that react to events on your BlinkURLs account. When an event occurs, we'll send a POST request with a JSON payload to your configured URL.

Event Types

link.createdEnterprise
Fires immediately when a new short link is created via account or API.
link.updatedMarketer
Fires when a link's destination, alias, or settings are modified.
link.deletedMarketer
Alerts when a short link is permanently removed.
click.createdEnterprise
Real-time data stream for every individual click (Visitor IP, OS, etc).
referral.createdPartner
Notifies a partner when their referral link leads to a new registration.

Payload Example

{
  "event": "click.created",
  "timestamp": "2024-03-20T12:05:00Z",
  "data": {
    "shortCode": "myBrand",
    "country": "US",
    "browser": "Chrome",
    "os": "iOS",
    "utm": {
      "source": "twitter",
      "medium": "social"
    }
  }
}

Tip: Use the "Test Webhook" button in your Settings to see the exact format for each event.

Rate Limits

API endpoints are rate-limited per API key: 60 req/min for link writes, 120 req/min for link reads, 60 req/min for domains, 10 req/min for bulk link creation (up to 50 links per request), and 20 req/min for aggregated analytics (cached for 5 minutes). Rate limit status headers (X-RateLimit-Remaining and X-RateLimit-Reset) are included in all responses. Need higher enterprise volume? Contact us.