Linktree Hello World

Overview

Minimal working examples demonstrating core Linktree API functionality.

Instructions

Step 1: Get Profile

const profile = await client.profiles.get('myprofile');
console.log(`Bio: ${profile.bio}`);
console.log(`Links: ${profile.links.length}`);

Step 2: Create a Link

const link = await client.links.create({
  profile_id: profile.id,
  title: 'My Website',
  url: 'https://example.com',
  position: 0,  // Top of list
  thumbnail: 'https://example.com/icon.png'
});
console.log(`Created link: ${link.id}`);

Step 3: Update Link

await client.links.update(link.id, {
  title: 'Updated Title',
  archived: false
});

Step 4: List All Links

const links = await client.links.list({ profile_id: profile.id });
links.forEach(l => console.log(`${l.position}: ${l.title} → ${l.url}`));

Error Handling

Resources

• Linktree API Docs

Next Steps

See linktree-local-dev-loop.

Linktree Production Checklist

Overview

Linktree profiles serve as the single gateway between a creator's social audience and their monetized destinations. A misconfigured integration can silently drop link-click analytics, leak API keys through client-side calls, or trip the 100 req/min rate limit during viral traffic spikes. This checklist hardens your Linktree API integration for production-grade reliability, ensuring click tracking stays accurate, webhook delivery remains verified, and your link-in-bio pages load under high concurrency.

Prerequisites

• Production Linktree API key (not sandbox/dev key)
• Secrets manager configured (Vault, AWS Secrets Manager, or GCP Secret Manager)
• Monitoring stack operational (Datadog, Grafana, or CloudWatch)
• Staging environment validated with synthetic traffic test

Authentication & Secrets

• [ ] API keys stored in vault/secrets manager (never in code or environment files)
• [ ] Key rotation schedule configured (every 90 days)
• [ ] Separate keys for staging vs production environments
• [ ] Bearer token included in Authorization header, not query params
• [ ] API key scopes restricted to minimum required permissions (read-only where possible)

API Integration

• [ ] Base URL points to https://api.linktr.ee/v1 (production, not sandbox)
• [ ] Rate limiting enforced client-side at 90 req/min (buffer below 100 req/min hard limit)
• [ ] Pagination implemented for profile link listing (cursor-based, not offset)
• [ ] Request timeout set to 10 seconds for profile reads, 30 seconds for analytics queries
• [ ] Content-Type: application/json and Accept headers set on every request
• [ ] Link click tracking webhook endpoint registered and reachable from Linktree servers
• [ ] Bulk link updates batched to avoid rate limit bursts during campaign launches

Error Handling & Resilience

• [ ] Circuit breaker configured for Linktree API calls (open after 5 consecutive failures)
• [ ] Retry logic with exponential backoff for 429 (rate limit) and 5xx responses
• [ ] 429 responses parse Retry-After header to schedule next attempt
• [ ] Graceful degradation serves cached profile data when API is unreachable
• [ ] Link click events queued locally during outages and replayed on recovery
• [ ] Timeout errors distinguished from authentication errors in alerting

Monitoring & Alerting

• [ ] API latency tracked (p50, p95, p99) with 500ms p95 threshold
• [ ] Error rate alerts configured (threshold: >1% over 5-minute window)
• [ ] Rate limit headroom monitored (alert when usage exceeds 80 req/min sustained)
• [ ] Click tracking event delivery lag measured (alert if >60s behind real-time)
• [

Linktree Reference Architecture

Overview

Design a read-optimized integration layer for the Linktree link-in-bio platform. The extreme read-to-write ratio on public profiles drives a two-tier cache with async analytics, keeping the hot path free from downstream blocking.

Instructions

1. Provision the prerequisites below and configure Linktree API credentials.
2. Deploy the service layer with the cache-aside pattern for profile reads.
3. Wire the webhook ingester to invalidate cache on profile mutations.
4. Start the click event consumer to populate the analytics store.
5. Adjust Redis TTLs and rate-limit buckets to match your traffic profile.

Prerequisites

• Node.js 18+, TypeScript 5, Redis 7, RabbitMQ or SQS, PostgreSQL 15
• Linktree API credentials with profile:read and links:write scopes

Architecture Diagram

Client --> API Gateway --> LinktreeService --> Linktree API
                                |
                 +--------------+--------------+
                 v              v              v
           Redis Cache    Event Queue    Analytics DB
           (profiles)    (clicks/views)  (aggregates)

Service Layer

class LinktreeService {
  constructor(
    private api: LinktreeApiClient,
    private cache: ProfileCache,
    private events: EventPublisher
  ) {}

  async getProfile(username: string): Promise<Profile> {
    const cached = await this.cache.get(`profile:${username}`);
    if (cached) return cached;
    const profile = await this.api.fetchProfile(username);
    await this.cache.set(`profile:${username}`, profile, 300);
    return profile;
  }

  async updateLinks(profileId: string, links: LinkUpdate[]): Promise<void> {
    await this.api.patchLinks(profileId, links);
    await this.cache.invalidate(`profile:${profileId}`);
    await this.events.publish('links.updated', { profileId, count: links.length });
  }
}

Caching Strategy

class ProfileCache {
  constructor(private redis: RedisClient) {}

  async get(key: string): Promise<Profile | null> {
    const raw = await this.redis.get(key);
    return raw ? JSON.parse(raw) : null;
  }

  async set(key: string, data: Profile, ttl: number): Promise<void> {
    await this.redis.setEx(key, ttl, JSON.stringify(data));
  }

  async invalidate(pattern: string): Promise<void> {
    const keys = await this.redis.keys(pattern);
    if (keys.length) await this.redis.del(keys);
  }
}
// TTLs: profiles 5 min, link lists 2 min, analytics summaries 15 min

Event Pipeline

class ClickEventConsumer {
  constructor(private queue: MessageQueue, private db: AnalyticsStore) {}

  async start(): Promise<void> {
    await this.queue.

Linktree SDK Patterns

Overview

Linktree's REST API exposes profile management, link CRUD, click analytics, and appearance theming through bearer-token authentication. A structured SDK client matters here because Linktree enforces strict per-minute rate limits on analytics endpoints and returns nested profile objects that benefit from strong typing. These patterns provide a thread-safe singleton, typed error classification, fluent request building for paginated link lists, and test utilities for mocking profile and analytics responses.

Prerequisites

• Node.js 18+, TypeScript 5+
• LINKTREEAPIKEY environment variable (generated in Linktree admin > Settings > Developer)
• axios or node-fetch for HTTP transport

Singleton Client

interface LinktreeConfig {
  apiKey: string;
  baseUrl?: string;
  timeout?: number;
}

let client: LinktreeClient | null = null;

export function getLinktreeClient(overrides?: Partial<LinktreeConfig>): LinktreeClient {
  if (!client) {
    const config: LinktreeConfig = {
      apiKey: process.env.LINKTREE_API_KEY ?? '',
      baseUrl: 'https://api.linktr.ee/v1',
      timeout: 10_000,
      ...overrides,
    };
    if (!config.apiKey) throw new Error('LINKTREE_API_KEY is required');
    client = new LinktreeClient(config);
  }
  return client;
}

Error Wrapper

interface LinktreeError { status: number; code: string; detail: string; }

async function safeLinktree<T>(fn: () => Promise<T>): Promise<T> {
  try { return await fn(); }
  catch (err: any) {
    const parsed: LinktreeError = {
      status: err.response?.status ?? 500,
      code: err.response?.data?.error?.code ?? 'UNKNOWN',
      detail: err.response?.data?.error?.message ?? err.message,
    };
    if (parsed.status === 429) {
      const retryAfter = parseInt(err.response?.headers?.['retry-after'] ?? '5', 10);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      return fn();
    }
    if (parsed.status === 401) throw new Error(`Auth failed: ${parsed.detail}`);
    throw new Error(`Linktree ${parsed.code} (${parsed.status}): ${parsed.detail}`);
  }
}

Request Builder

class LinkQueryBuilder {
  private params: Record<string, string> = {};
  forProfile(id: string) { this.params.profile_id = id; return this; }
  active(only = true) { this.params.is_active = String(only); return this; }
  page(cursor: string) { this.params.cursor = cursor; return this; }
  limit(n: number) { this.params.limit = String(Math.min(n, 100)); return this; }
  build(): URLSearchParams { return new URLSearchParams(this.params); }
}

Response Types

interface LinktreeProfile 

Linktree Security Basics

Overview

Linktree integrations handle user-generated content (link titles, URLs, bios) and analytics data that is PII-adjacent — click counts, geographic breakdowns, and referrer URLs can fingerprint individual visitors. Bearer token authentication means a leaked key grants full account access including link creation, profile modification, and analytics export. Webhook payloads carry real-time event data signed with HMAC-SHA256, and failing to verify signatures opens your endpoint to spoofed events and data poisoning.

Prerequisites

• Secrets manager (AWS SSM, GCP Secret Manager, or Vault) for all Linktree credentials
• HTTPS enforced on all webhook receiver endpoints
• .env files in .gitignore — never committed to version control
• Logging infrastructure that supports field-level redaction

API Key Management

// Load Linktree bearer token from environment — never hardcode
const LINKTREE_TOKEN = process.env.LINKTREE_API_KEY;

function validateLinktreeConfig(): void {
  if (!LINKTREE_TOKEN || LINKTREE_TOKEN.startsWith('lt_test_')) {
    throw new Error('Missing or test-only LINKTREE_API_KEY — set a production token');
  }
}

function linktreeHeaders(): Record<string, string> {
  return {
    Authorization: `Bearer ${LINKTREE_TOKEN}`,
    'Content-Type': 'application/json',
  };
}
// Call validateLinktreeConfig() at startup, before accepting requests

Webhook Signature Verification

import crypto from 'node:crypto';

const WEBHOOK_SECRET = process.env.LINKTREE_WEBHOOK_SECRET!;

function verifyLinktreeWebhook(payload: string, signature: string): boolean {
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload, 'utf8')
    .digest('hex');
  // Timing-safe comparison prevents timing attacks
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// Express middleware
app.post('/webhooks/linktree', (req, res) => {
  const sig = req.headers['x-linktree-signature'] as string;
  if (!sig || !verifyLinktreeWebhook(JSON.stringify(req.body), sig)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  // Process verified event
});

Input Validation

import { URL } from 'node:url';

function sanitizeLinkTitle(title: string): string {
  // Strip HTML/script tags from user-generated link titles
  return title.replace(/<[^>]*>/g, '').trim().slice(0, 150);
}

function validateLinkUrl(url: string): boolean {
  try {
    const parsed = new URL(url);
    // Only allow http/https — block javascript:, data:, file: schemes
    return ['http:', 'https:'].includes(parsed.protocol);
  } 

Linktree Upgrade & Migration

Overview

Linktree provides a link-in-bio platform with APIs for managing profiles, links, and click analytics. The API exposes endpoints for CRUD operations on link trees, individual links, and analytics data. Tracking API changes is critical because Linktree's link schema evolves with new link types (commerce, scheduling, music), analytics response formats change with new metric dimensions, and profile customization fields expand — breaking integrations that sync link performance data to marketing dashboards or automate link management across multiple profiles.

Version Detection

const LINKTREE_BASE = "https://api.linktr.ee/v1";

async function detectLinktreeApiVersion(apiKey: string): Promise<void> {
  const res = await fetch(`${LINKTREE_BASE}/profile`, {
    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  });
  const version = res.headers.get("x-linktree-api-version") ?? "v1";
  console.log(`Linktree API version: ${version}`);

  // Check for deprecated link type fields
  const linksRes = await fetch(`${LINKTREE_BASE}/links`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const data = await linksRes.json();
  const knownTypes = ["classic", "header", "music", "video", "commerce", "scheduling"];
  const activeTypes = [...new Set(data.links?.map((l: any) => l.type) ?? [])];
  const unknown = activeTypes.filter((t: string) => !knownTypes.includes(t));
  if (unknown.length) console.log(`New link types detected: ${unknown.join(", ")}`);
}

Migration Checklist

• [ ] Review Linktree developer changelog for API breaking changes
• [ ] Audit codebase for hardcoded link type enums (new types may be added)
• [ ] Verify analytics endpoint response structure (metrics, dimensions, date ranges)
• [ ] Check profile customization fields for new appearance options
• [ ] Update link creation payload if required fields were added
• [ ] Test link ordering API — sort mechanism may have changed
• [ ] Validate thumbnail/image upload endpoints for size or format changes
• [ ] Check OAuth token scopes if new permissions required for analytics
• [ ] Update webhook handlers for link click and profile view events
• [ ] Run analytics data export and compare old vs. new response shapes

Schema Migration

// Linktree links evolved: simple URL → typed link with metadata
interface OldLink {
  id: string;
  title: string;
  url: string;
  position: number;
  active: boolean;
}

interface NewLink {
  id: string;
  title: string;
  url: string;
  type: "classic" | "header" | "music" | "video" | "commerce" | "

Linktree Webhooks & Events

Overview

Linktree emits real-time webhook events whenever links, profiles, or analytics milestones change. These events enable automations such as syncing new bio links to a CMS, triggering social media posts when a profile is updated, alerting marketing teams when traffic milestones are hit, and auditing link lifecycle changes for compliance dashboards. All payloads are JSON over HTTPS with HMAC-SHA256 signature verification to guarantee authenticity.

Prerequisites

• A registered Linktree developer app with webhook permissions enabled
• Webhook endpoint URL accessible over HTTPS (TLS 1.2+)
• Signing secret from the Linktree developer dashboard (LINKTREEWEBHOOKSECRET)
• Express.js with raw body parsing enabled for signature verification

Webhook Registration

import axios from "axios";

const res = await axios.post(
  "https://api.linktr.ee/v1/webhooks",
  {
    url: "https://your-app.com/webhooks/linktree",
    events: ["link.created", "link.updated", "link.deleted",
             "profile.updated", "analytics.milestone"],
  },
  { headers: { Authorization: `Bearer ${process.env.LINKTREE_API_TOKEN}` } }
);
console.log("Subscription ID:", res.data.id);

Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyLinktreeSignature(req: Request, res: Response, next: NextFunction) {
  const signature = req.headers["x-linktree-signature"] as string;
  const timestamp = req.headers["x-linktree-timestamp"] as string;
  if (!signature || !timestamp) return res.status(401).send("Missing signature");

  const payload = `${timestamp}.${(req as any).rawBody}`;
  const expected = crypto
    .createHmac("sha256", process.env.LINKTREE_WEBHOOK_SECRET!)
    .update(payload)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(403).send("Invalid signature");
  }
  next();
}

Event Handler

app.post("/webhooks/linktree", verifyLinktreeSignature, (req, res) => {
  const { type, data, timestamp } = req.body;

  switch (type) {
    case "link.created":
      console.log(`New link: ${data.title} → ${data.url}`);
      break;
    case "link.updated":
      console.log(`Link edited: ${data.link_id}, position: ${data.position}`);
      break;
    case "link.deleted":
      console.log(`Link removed: ${data.link_id}`);
      break;
    case "profile.updated":
      console.log(`Profile changed: bio=${data.bio}, avatar=${data.avatar_url