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 while Klinky is early

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, multi-client 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:

bash

# 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:

json

{
  "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:

bash

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

Getting Your API Key

Log in to app.klinky.io
Navigate to Settings > API Keys
Click Create New Key
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 API keys to be enabled for your account

Rate Limits

API access is available when API keys are enabled for your account. Response headers show your current hourly limit.

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

bash

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

bash

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

Get Click Analytics

bash

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

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}
    ]
}

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

javascript

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

<?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:

bash

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
Infrastructure notes: See the Trust page
Feature requests: We're listening — send us your ideas

Create your free account — Build your first A/B test link today

Getting Started with the Klinky API ​

What You Can Build ​

Who Is This For? ​

Quick Win: Create Your First A/B Test Link ​

Base URL ​

Authentication ​

Getting Your API Key ​

Rate Limits ​

Core Operations ​

Create a Link ​

List Your Links ​

Get Click Analytics ​

SDK Examples ​

Python ​

JavaScript/Node.js ​

PHP ​

Idempotency for Safe Retries ​

Next Steps ​

Build Your Integration ​

Handle Edge Cases ​

Need Help? ​

Getting Started with the Klinky API

What You Can Build

Who Is This For?

Quick Win: Create Your First A/B Test Link

Base URL

Authentication

Getting Your API Key

Rate Limits

Core Operations

Create a Link

List Your Links

Get Click Analytics

SDK Examples

Python

JavaScript/Node.js

PHP

Idempotency for Safe Retries

Next Steps

Build Your Integration

Handle Edge Cases

Need Help?