API Reference

Authorization: Bearer klup_a1b2c3d4…64hexchars
Content-Type: application/json

klup_<64 lowercase hexadecimal characters>

{
  "success": true,
  "data": { ... }          // returned resource or array
}

{
  "success": false,
  "error": "Human-readable message",
  "details": { ... }       // optional: per-field validation errors
}

curl -X POST https://klookup.com/api/v1/links \
  -H "Authorization: Bearer klup_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/sensitive-download.zip",
    "type": "inpage",
    "post_id": "post_42",
    "title": "Download: Example App v2.0",
    "description": "This file has been verified safe by our team."
  }'

{
  "success": true,
  "data": {
    "id": 99,
    "short_code": "xYz5678",
    "short_url": "https://klookup.com/xYz5678/page",
    "target_url": "https://example.com/sensitive-download.zip",
    "type": "inpage",
    "title": "Download: Example App v2.0",
    "description": "This file has been verified safe by our team.",
    "expires_at": null,
    "post_id": "post_42",
    "site_url": "https://example.com/sensitive-download.zip",
    "site_verified_at": null,
    "created_at": "2026-02-22T12:00:00Z"
  }
}

curl -X POST https://klookup.com/api/v1/links \
  -H "Authorization: Bearer klup_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-destination.com",
    "type": "inpage",
    "title": "Visit our partner site",
    "description": "This link has been reviewed by our team."
  }'

const API_KEY = process.env.KLOOKUP_API_KEY; // klup_…

async function createInPageLink(url, title, description) {
  const res = await fetch("https://klookup.com/api/v1/links", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url,
      type: "inpage",
      title,
      description,
    }),
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error ?? "Failed to create link");
  }

  const { data } = await res.json();
  return data.short_url; // "https://klookup.com/xYz5678/page"
}

const safeLink = await createInPageLink(
  "https://example.com/file.zip",
  "Download Example App",
  "Verified safe — click proceed to download."
);
console.log(safeLink);

interface CreateLinkOptions {
  url: string;
  type?: "direct" | "inpage";
  /** Required when type is "inpage" — unique ID of the post/page on your site */
  post_id?: string;
  title?: string;
  description?: string;
  expires_at?: string;    // ISO-8601
  /**
   * Your website URL where this inpage link will be embedded.
   * Triggers automatic site verification — the link is deleted after 24 h
   * if Klook Up cannot find it on the page.
   */
  site_url?: string;
}

interface KlookUpLink {
  id: number;
  short_code: string;
  short_url: string;
  target_url: string;
  type: "direct" | "inpage";
  post_id?: string | null;
  site_url?: string | null;
  site_verified_at?: string | null;
  created_at: string;
  /** true when post_id was provided and an existing link was returned instead of creating a new one */
  existing?: boolean;
}

class KlookUpClient {
  constructor(private readonly apiKey: string) {}

  async createLink(opts: CreateLinkOptions): Promise<KlookUpLink> {
    const res = await fetch("https://klookup.com/api/v1/links", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${this.apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(opts),
    });
    const body = await res.json() as { success: boolean; data: KlookUpLink; error?: string };
    if (!res.ok || !body.success) throw new Error(body.error ?? "API error");
    return body.data;
  }
}

// Usage
const client = new KlookUpClient(process.env.KLOOKUP_API_KEY!);
const link = await client.createLink({
  url: "https://example.com",
  type: "inpage",
  title: "Our partner site",
});
console.log(link.short_url);

import os
import requests

API_KEY = os.environ["KLOOKUP_API_KEY"]  # klup_…
BASE_URL = "https://klookup.com/api/v1"

def create_link(url: str, link_type: str = "direct", **kwargs) -> dict:
    """
    Create a Klook Up short link.
    link_type: "direct" or "inpage"
    kwargs: post_id (required for inpage), title, description, expires_at, site_url
    """
    payload = {"url": url, "type": link_type, **kwargs}
    response = requests.post(
        f"{BASE_URL}/links",
        json=payload,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        timeout=10,
    )
    response.raise_for_status()
    return response.json()["data"]

# Create an in-page safety link
link = create_link(
    url="https://example.com/confidential.pdf",
    link_type="inpage",
    title="Confidential Document",
    description="Please verify you are authorised before proceeding.",
)
print(link["short_url"])  # https://klookup.com/xYz5678/page

<?php

function klookup_create_link(string $apiKey, array $payload): array {
    $ch = curl_init("https://klookup.com/api/v1/links");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode($payload),
        CURLOPT_HTTPHEADER     => [
            "Authorization: Bearer $apiKey",
            "Content-Type: application/json",
        ],
        CURLOPT_TIMEOUT        => 10,
    ]);
    $body   = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $json = json_decode($body, true);
    if ($status >= 400 || !$json['success']) {
        throw new RuntimeException($json['error'] ?? 'API error');
    }
    return $json['data'];
}

$link = klookup_create_link(getenv('KLOOKUP_API_KEY'), [
    'url'         => 'https://example.com/download',
    'type'        => 'inpage',
    'title'       => 'Download our software',
    'description' => 'Verified safe by our security team.',
]);

echo $link['short_url']; // https://klookup.com/xYz5678/page