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

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" | "scheduling";
  position: number;
  active: boolean;
  metadata: {
    thumbnail_url?: string;
    schedule?: { start: string; end: string };
    price?: { amount: number; currency: string };
  };
  analytics: { total_clicks: number; unique_clicks: number };
}

function migrateLink(old: OldLink): NewLink {
  return {
    ...old,
    type: "classic",
    metadata: {},
    analytics: { total_clicks: 0, unique_clicks: 0 },
  };
}

Rollback Strategy

class LinktreeClient {
  private version: "v1" | "v2";

  constructor(private apiKey: string, version: "v1" | "v2" = "v2") {
    this.version = version;
  }

  async getLinks(): Promise<any> {
    try {
      const res = await fetch(`https://api.linktr.ee/${this.version}/links`, {
        headers: { Authorization: `Bearer ${this.apiKey}` },
      });
      if (!res.ok) throw new Error(`Linktree ${res.status}`);
      return await res.json();
    } catch (err) {
      if (this.version === "v2") {
        console.warn("Falling back to Linktree API v1");
        this.version = "v1";
        return this.getLinks();
      }
      throw err;
    }
  }
}

Error Handling

Migration Issue	Symptom	Fix
Link type enum expanded	`400` when filtering by type with old enum values	Fetch current types from `/link-types` and update filter logic
Analytics response restructured	`undefined` accessing `link.clicks` (now `link.analytics.total_clicks` )	Update property paths to new nested analytics object
Profile field renamed	`avatar_url` returns `null` , now `profile_image_url`	Update all references to use new field name
Thumbnail upload format changed	`415 Unsupported Media Type` on image upload	Check supported formats via `/upload/formats` endpoint
Rate limit per-endpoint	`429` on analytics but not links	Implement per-endpoint rate limiting instead of global

Resources

Next Steps

For CI pipeline integration, see

linktree-ci-integration

Claude-code-plugins-plus-skills linktree-upgrade-migration