Getting Started with the Klinky API

Build smarter links programmatically. The Klinky API lets you create A/B tests, track conversions, and optimize campaigns—all through code.

Start building smarter links — Free 14-day trial, no credit card required

---

What You Can Build

The Klinky link shortener API helps developers and marketers automate link management at scale:

• A/B Testing at Scale — Create hundreds of test links programmatically
• Conversion Tracking — Track meaningful outcomes beyond clicks
• Geo-Routing — Route visitors to location-optimized destinations
• Auto-Optimization — Let algorithms direct traffic to winning variants
• Analytics Integration — Pull click data into your BI tools

Who Is This For?

Role	Common Use Cases
Growth Engineers	Automate test creation, integrate with internal tools
Marketing Teams	Bulk link generation, campaign automation
Agencies	Client reporting, white-label link management
E-commerce	Product page testing, regional store routing
SaaS Companies	Onboarding flow optimization, pricing tests

Quick Win: Create Your First A/B Test Link

Get results in under 5 minutes:

# 1. Set your API key
API_KEY="klinky_live_your_api_key_here"

# 2. Create a link with two variants
curl -X POST https://klinky-api.fly.dev/api/v1/public/links \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Homepage Headline Test",
    "slug": "homepage-test",
    "variants": [
      {
        "label": "control",
        "destination_url": "https://example.com/home",
        "weight": 50
      },
      {
        "label": "new_headline",
        "destination_url": "https://example.com/home-v2",
        "weight": 50
      }
    ]
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "homepage-test",
  "short_url": "https://klinky.io/homepage-test",
  "variants": [...]
}

Your trackable short link is now live. Share klinky.io/homepage-test and watch the data roll in.

---

Base URL

All API requests use:

https://klinky-api.fly.dev/api/v1

Authentication

Include your API key in the X-API-Key header:

curl -H "X-API-Key: klinky_live_your_api_key_here" \
  https://klinky-api.fly.dev/api/v1/public/links

Getting Your API Key

1. Log in to app.klinky.io
2. Navigate to Settings > API Keys
3. Click Create New Key
4. Copy immediately — the full key is shown only once

Security note: Store API keys in environment variables, never in code repositories.

Get API access — Requires Growth plan or higher

---

Rate Limits

API access is available on Growth and Scale plans:

Plan	API Access	Rate Limit	Best For
Free/Starter	No	—	Dashboard only
Growth	Yes	100/hour	Small teams, basic automation
Scale	Yes	1,000/hour	Large teams, heavy API usage

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1705312800

Learn more about rate limit best practices.

---

Core Operations

Create a Link

curl -X POST https://klinky-api.fly.dev/api/v1/public/links \
  -H "X-API-Key: klinky_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Campaign Test",
    "slug": "campaign-test",
    "variants": [
      {"label": "a", "destination_url": "https://a.com", "weight": 50},
      {"label": "b", "destination_url": "https://b.com", "weight": 50}
    ]
  }'

List Your Links

curl https://klinky-api.fly.dev/api/v1/public/links \
  -H "X-API-Key: klinky_live_your_api_key_here"

Get Click Analytics

curl https://klinky-api.fly.dev/api/v1/public/links/{id}/clicks \
  -H "X-API-Key: klinky_live_your_api_key_here"

See the Links API and Analytics API for complete reference.

---

SDK Examples

Python

import requests

API_KEY = "klinky_live_your_api_key_here"
BASE_URL = "https://klinky-api.fly.dev/api/v1"

headers = {"X-API-Key": API_KEY}

# Create an A/B test link
link_data = {
    "name": "Pricing Page Test",
    "slug": "pricing-test",
    "variants": [
        {"label": "control", "destination_url": "https://example.com/pricing", "weight": 50},
        {"label": "discount", "destination_url": "https://example.com/pricing-sale", "weight": 50}
    ],
    "auto_winner": True,
    "auto_winner_threshold": 200
}

response = requests.post(
    f"{BASE_URL}/public/links",
    headers=headers,
    json=link_data
)
link = response.json()
print(f"Created trackable short link: klinky.io/{link['slug']}")

# List all links with performance data
response = requests.get(f"{BASE_URL}/public/links", headers=headers)
links = response.json()["items"]
for link in links:
    print(f"{link['name']}: {link['total_clicks']} clicks, {link['total_conversions']} conversions")

JavaScript/Node.js

const API_KEY = 'klinky_live_your_api_key_here';
const BASE_URL = 'https://klinky-api.fly.dev/api/v1';

// Create a conversion-tracking link
const createLink = async () => {
  const response = await fetch(`${BASE_URL}/public/links`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Newsletter Signup Test',
      slug: 'newsletter-test',
      variants: [
        { label: 'short_form', destination_url: 'https://example.com/quick-signup', weight: 50 },
        { label: 'long_form', destination_url: 'https://example.com/full-signup', weight: 50 }
      ]
    })
  });

  const link = await response.json();
  console.log(`Created smart link: klinky.io/${link.slug}`);
  return link;
};

// Fetch analytics data
const getAnalytics = async (linkId) => {
  const response = await fetch(`${BASE_URL}/public/links/${linkId}/clicks`, {
    headers: { 'X-API-Key': API_KEY }
  });
  return response.json();
};

PHP

<?php
$apiKey = 'klinky_live_your_api_key_here';
$baseUrl = 'https://klinky-api.fly.dev/api/v1';

// Create a geo-routed link
$ch = curl_init("$baseUrl/public/links");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: $apiKey",
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'Regional Store Test',
    'slug' => 'store-test',
    'routing_type' => 'geo',
    'variants' => [
        ['label' => 'us_store', 'destination_url' => 'https://us.example.com', 'weight' => 50],
        ['label' => 'eu_store', 'destination_url' => 'https://eu.example.com', 'weight' => 50]
    ],
    'geo_rules' => [
        'US' => 'us_store',
        'CA' => 'us_store',
        'DE' => 'eu_store',
        'FR' => 'eu_store',
        'default' => 'us_store'
    ]
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$link = json_decode($response, true);
echo "Created geo-routed link: klinky.io/{$link['slug']}\n";
curl_close($ch);
?>

---

Idempotency for Safe Retries

Include an Idempotency-Key header to safely retry failed requests without creating duplicates:

curl -X POST https://klinky-api.fly.dev/api/v1/public/links \
  -H "X-API-Key: klinky_live_your_api_key_here" \
  -H "Idempotency-Key: unique-key-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{...}'

Use a UUID or hash of request parameters as your key.

---

Next Steps

Build Your Integration

• Authentication — Manage API keys and security
• Links API — Full link management reference
• Analytics API — Retrieve click and conversion data

Handle Edge Cases

• Error Handling — Complete error reference with examples
• Rate Limits — Strategies for high-volume usage

---

Need Help?

• Questions? Email support@klinky.io
• Status: Check status.klinky.io
• Feature requests: We're listening — send us your ideas

Start your free trial — Build your first A/B test link today