# melinks — Full Documentation for LLMs

> melinks is a link-in-bio service built for AI agents. Create, manage, and share link pages via MCP or REST API — no UI required.

## Overview

melinks lets anyone create a shareable link-in-bio page with a single API call. No sign-up, no authentication needed for creation. Pages go live instantly at `https://melinks.co/l/{shortcode}`. Users can later claim ownership, choose a vanity username (`https://melinks.co/{username}`), and manage pages from a dashboard.

## When to use melinks

Use melinks when a user asks you to:
- Create a link-in-bio page, link page, or link list
- Make a page with multiple links to share
- Set up a "link in bio" for social media
- Create a personal landing page with links
- Organize and share a collection of URLs
- Export or import link collections as portable JSON

## MCP Server (recommended)

**Endpoint:** `https://melinks.co/mcp`
**Protocol:** Model Context Protocol (MCP) over HTTP
**Discovery:** `https://melinks.co/.well-known/mcp.json`

### Setup

For Claude Desktop, Cursor, or Windsurf:
```json
{
  "mcpServers": {
    "melinks": {
      "url": "https://melinks.co/mcp"
    }
  }
}
```

For VS Code (`.vscode/mcp.json`):
```json
{
  "servers": {
    "melinks": {
      "type": "http",
      "url": "https://melinks.co/mcp"
    }
  }
}
```

### MCP Tools (14 total)

#### create_link_list
Create a new link page. No authentication required.

Parameters:
- `display_name` (string, required): Name shown at top of the page (1-100 chars)
- `bio` (string, optional): Short bio or description (max 500 chars)
- `avatar_url` (string, optional): Avatar image URL (http/https only)
- `theme` (string, optional): One of `default`, `dark`, `minimal`, `bold`, `pastel`, `custom`
- `custom_theme` (object, optional): 7 hex color fields (bg, text, muted, card, cardText, border, cardHover)
- `button_style` (string, optional): One of `rounded`, `pill`, `sharp`, `soft`
- `links` (array, required): 1-50 items, each with `type` (optional, default `link`, one of `link`/`header`/`text`), `title` (required), `url` (required for type=link), `icon` (optional)
- `seo_title` (string, optional): Custom Open Graph title (max 100 chars, falls back to display_name)
- `seo_description` (string, optional): Custom Open Graph description (max 200 chars, falls back to bio)
- `seo_image` (string, optional): Custom Open Graph image URL (falls back to avatar_url)

Returns: `url`, `shortcode`, `claim_token`, `claim_url`

#### get_link_list
Retrieve a link page by shortcode or username. Read-only, no auth required.

Parameters:
- `identifier` (string, required): Shortcode or username

Returns: Full link list data including all links, theme, display name, bio, etc.

#### update_link_list
Update an existing link page. Requires claim token or API key.

Parameters:
- `identifier` (string, required): Shortcode or username
- `auth_token` (string, required): Claim token or API key
- Same fields as create (all optional for partial updates)

#### delete_link_list
Permanently delete a link page. Requires claim token or API key.

Parameters:
- `identifier` (string, required): Shortcode or username
- `auth_token` (string, required): Claim token or API key

#### export_link_list
Export a link page as melinks JSON v1 format. Read-only, no auth required.

Parameters:
- `identifier` (string, required): Shortcode or username

Returns: `melinks_version`, `exported_at`, `link_list` object

#### import_link_list
Create a new link page (or overwrite an existing one) from melinks JSON v1 format.

Parameters:
- `json_data` (string, required): JSON string in melinks v1 format
- `identifier` (string, optional): Shortcode or username of existing list to overwrite
- `auth_token` (string, optional): Required if overwriting an existing list

#### get_qr_code
Generate a downloadable QR code for a link page. Returns base64-encoded SVG and a download URL.

Parameters:
- `identifier` (string, required): Shortcode or username
- `size` (number, optional): QR code size in pixels (128–1024, default 256)

Returns: `svg_base64`, `download_url`, `page_url`

#### list_versions
View version history for a link page. Requires claim token or API key.

Parameters:
- `identifier` (string, required): Shortcode or username
- `auth_token` (string, required): Claim token or API key
- `limit` (number, optional): Max results (1–50, default 10)
- `offset` (number, optional): Pagination offset (default 0)

Returns: `versions[]` (version_number, change_summary, created_at), `total`

#### rollback_version
Roll back a link page to a previous version. Saves the current state as a new version first. Requires claim token or API key.

Parameters:
- `identifier` (string, required): Shortcode or username
- `auth_token` (string, required): Claim token or API key
- `version_number` (number, required): Version number to restore

Returns: `new_version_number`

#### get_analytics (Pro)
Get detailed click analytics for a link page. Requires API key from a Pro subscriber.

Parameters:
- `identifier` (string, required): Shortcode or username
- `auth_token` (string, required): API key
- `range` (string, optional): Time range — `7d`, `30d`, or `90d` (default: `30d`)

Returns: `range`, `total_clicks`, `time_series[]` (date + clicks), `countries[]`, `referrers[]`, `links[]` (per-link breakdown)

#### create_ab_test (Pro)
Start an A/B test. Variant A is the current page state. Variant B is a provided snapshot.

Parameters:
- `identifier` (string, required): Shortcode or username
- `auth_token` (string, required): API key
- `variant_b` (object, required): Full page snapshot for variant B (same shape as link list data)
- `traffic_split` (number, optional): % of traffic to variant B (0-100, default: 50)

Returns: `test_id`

#### get_ab_test (Pro)
Get A/B test status and per-variant click stats.

Parameters:
- `identifier` (string, required): Shortcode or username
- `auth_token` (string, required): API key

Returns: `active`, `test_id`, `status`, `traffic_split`, `winner`, `variant_a` stats, `variant_b` stats

#### conclude_ab_test (Pro)
End an A/B test and apply the winning variant to the live page.

Parameters:
- `identifier` (string, required): Shortcode or username
- `auth_token` (string, required): API key
- `winner` (string, required): `a` or `b`

#### cancel_ab_test (Pro)
Cancel an A/B test without applying changes. Deletes test data.

Parameters:
- `identifier` (string, required): Shortcode or username
- `auth_token` (string, required): API key

## REST API

**Base URL:** `https://melinks.co/api/v1`
**OpenAPI spec:** `https://melinks.co/openapi.yaml`

### Endpoints

#### POST /api/v1/links
Create a new link list. No auth required. Rate limited: 10/hour per IP.

Request body:
```json
{
  "display_name": "My Links",
  "bio": "A collection of my favorite links",
  "theme": "dark",
  "button_style": "pill",
  "links": [
    { "title": "GitHub", "url": "https://github.com/username" },
    { "type": "header", "title": "Social Media" },
    { "title": "Twitter", "url": "https://twitter.com/username" },
    { "type": "text", "title": "Follow me for updates and announcements" },
    { "title": "My Blog", "url": "https://example.com" }
  ],
  "seo_title": "My Custom Title",
  "seo_description": "Custom description for social sharing"
}
```

Response (201):
```json
{
  "url": "https://melinks.co/l/a1b2c3",
  "shortcode": "a1b2c3",
  "claim_token": "ct_...",
  "claim_url": "https://melinks.co/claim/a1b2c3"
}
```

#### GET /api/v1/links/{id}
Get a link list by shortcode or username. No auth required.

#### PUT /api/v1/links/{id}
Update a link list. Requires `Authorization: Bearer {claim_token_or_api_key}`.

#### DELETE /api/v1/links/{id}
Delete a link list. Requires `Authorization: Bearer {claim_token_or_api_key}`.

#### GET /api/v1/links/{id}/export
Export a link list as melinks JSON v1 format. No auth required.

#### POST /api/v1/links/import
Create a new link list from melinks JSON v1 import. Rate limited: 10/hour per IP.

#### PUT /api/v1/links/{id}/import
Overwrite an existing link list from JSON import. Requires Bearer auth.

#### GET /api/v1/links/{id}/qr
Download a QR code for the link page as SVG. Query: `?size=128-1024` (default 256). No auth required.

#### GET /api/v1/links/{id}/versions
List version history for a link list. Requires Bearer auth. Query: `?limit=10&offset=0`.

#### GET /api/v1/links/{id}/versions/{version}
Get a specific version with full snapshot. Requires Bearer auth.

#### POST /api/v1/links/{id}/rollback
Rollback to a previous version. Saves current state first. Requires Bearer auth. Body: `{ "version_number": 3 }`.

#### POST /api/v1/images
Upload an image (avatar, SEO, or thumbnail). Max 3MB, JPEG/PNG/WebP/GIF. Requires Bearer auth. Returns `{ "url": "..." }`.

#### GET /api/v1/images/{path}
Serve an uploaded image. Long-lived cache headers. No auth required.

#### GET /api/v1/links/{id}/analytics
Get click analytics (Pro). Query: `?range=7d|30d|90d`. Returns time series, countries, referrers, per-link breakdown.

#### POST /api/v1/links/{id}/ab-test
Create an A/B test (Pro). Body: `{ variant_b: Snapshot, traffic_split?: number }`.

#### GET /api/v1/links/{id}/ab-test
Get A/B test status and stats (Pro).

#### PUT /api/v1/links/{id}/ab-test
Update A/B test (Pro). Body: `{ traffic_split?, variant_b?, status? }`.

#### DELETE /api/v1/links/{id}/ab-test
Cancel A/B test (Pro).

#### POST /api/v1/links/{id}/ab-test/conclude
Conclude A/B test (Pro). Body: `{ winner: "a" | "b" }`. Applies winner to live page.

#### POST /api/v1/domains
Register a custom domain (Pro). Body: `{ "domain": "links.example.com", "link_list_id": "..." }`. Requires Bearer auth.

#### GET /api/v1/domains
List all custom domains for the authenticated user (Pro). Requires Bearer auth.

#### GET /api/v1/domains/{id}
Refresh and get custom domain status (Pro). Requires Bearer auth.

#### DELETE /api/v1/domains/{id}
Remove a custom domain (Pro). Requires Bearer auth.

## Themes

Built-in themes: `default` (dark monochrome), `dark` (true black), `minimal` (light/white), `bold` (deep indigo/purple), `pastel` (light pink).

Custom theme with 7 hex color properties: `bg`, `text`, `muted`, `card`, `cardText`, `border`, `cardHover`.

Google Fonts (Pro): Inter, Roboto, Open Sans, Lato, Montserrat, Playfair Display, Merriweather, Source Code Pro, Nunito, Raleway, Poppins.

## Button Styles

`rounded` (border-radius: lg), `pill` (border-radius: full), `sharp` (square corners), `soft` (border-radius: md).

## Icon Auto-Detection

Icons are automatically detected from URLs for 35+ platforms including: GitHub, Twitter/X, Instagram, LinkedIn, YouTube, TikTok, Facebook, Twitch, Discord, Reddit, Snapchat, Pinterest, Medium, Dev.to, Stack Overflow, Dribbble, Behance, Figma, Spotify, SoundCloud, Apple Music, Telegram, WhatsApp, Mastodon, Threads, Bluesky, CodePen, NPM, GitLab, Patreon, Ko-fi, Buy Me a Coffee, PayPal, Notion, Substack.

## melinks JSON v1 Format (Import/Export)

```json
{
  "melinks_version": "1.0",
  "exported_at": "2025-01-01T00:00:00.000Z",
  "link_list": {
    "display_name": "My Links",
    "bio": "Optional bio",
    "avatar_url": "https://example.com/avatar.jpg",
    "theme": "default",
    "button_style": "rounded",
    "links": [
      { "title": "GitHub", "url": "https://github.com/user", "icon": "github" },
      { "type": "header", "title": "Other Links" },
      { "title": "Blog", "url": "https://example.com" },
      { "type": "text", "title": "Thanks for visiting my page!" }
    ],
    "seo_title": "Optional custom og:title",
    "seo_description": "Optional custom og:description",
    "seo_image": "https://example.com/og-image.jpg"
  }
}
```

## Authentication Model

- **No auth required** for: creating pages, reading pages, exporting pages, importing (creates new)
- **Bearer token required** for: updating, deleting, overwriting via import
- Token types: claim token (returned at creation, 7-day expiry) or API key (created in dashboard, no expiry)
- Auth header format: `Authorization: Bearer {token}`

## Rate Limits

- POST /api/v1/links: 10 requests/hour per IP
- POST /api/v1/links/import: 10 requests/hour per IP
- POST /mcp: 30 requests/hour per IP
- GET (all reads): 100 requests/minute per IP

## Additional Features

### Link Scheduling
Set `visible_from` and `visible_until` (UNIX timestamps) on any link to control when it appears. Links outside the window are hidden from the public page but remain in the dashboard.

### Mobile Deep Linking
Automatically generates platform-specific deep links on mobile. Android uses `intent://` URIs with fallback. iOS relies on Universal Links. Supports 25+ platforms including YouTube, Instagram, Twitter/X, TikTok, Spotify, and more.

### Link Thumbnails
Upload an image to display alongside a link. Supported via the image upload API (`POST /api/v1/images` with `purpose: "thumbnail"`). Shows as a small preview image on the link card.

### PIN-Protected Pages
Set a 4–8 digit PIN on a page to restrict access. Visitors must enter the PIN to view the content. Configured via dashboard or API.

### QR Codes
Every link page has a downloadable SVG QR code. Generate via `GET /api/v1/links/{id}/qr?size=256` or the `get_qr_code` MCP tool. Edge-generated, no third-party services.

### Version History
Every edit creates an immutable snapshot. View history via `GET /api/v1/links/{id}/versions` or `list_versions` MCP tool. Roll back with `POST /api/v1/links/{id}/rollback` or `rollback_version` MCP tool. Current state is saved before rollback.

### Embeddable Widget
Embed a link page on any external site via an iframe at `/embed/{shortcode}`.

### Custom Domains (Pro)
Connect your own domain (e.g. `links.example.com`) to a link page. Uses Cloudflare Custom Hostnames with automatic HTTPS provisioning. Up to 3 custom domains per account. Manage via `POST /api/v1/domains`, `GET /api/v1/domains`, `DELETE /api/v1/domains/{id}`.

### Email Collection (Pro)
Add email signup blocks (`type: "email_signup"`) to a page. Collected emails viewable in the dashboard. Optional webhook integration for external services.

### Rich Media Embeds (Pro)
Add embed content blocks (`type: "embed"`) to display YouTube, Spotify, SoundCloud, and other media directly on the page.

### Spotlight Links (Pro)
Mark one link per page as a spotlight. Gets special styling: larger card, accent border, box shadow glow, and optional star/pin badge.

### Branding Removal (Pro)
Hide the "Powered by MeLinks" footer on your public pages.

## Pricing

- **Free**: Up to 5 link pages, built-in themes and button styles, all core features (scheduling, deep links, thumbnails, QR codes, versioning, import/export, MCP, API, passkey auth)
- **Pro** (£3/month): Unlimited pages, custom themes + 11 fonts, branding removal, custom domains, detailed analytics, A/B testing, email collection, embeds, spotlight links

## Agent Skill

melinks provides an AgentSkills-compatible skill (agentskills.io) that teaches AI agents when and how to use melinks. The skill includes tool reference, guided workflows, and setup instructions for all major platforms.

### Installation

- **Claude Code**: `git clone https://github.com/melinks/skill .claude/skills/melinks`
- **OpenClaw**: `openclaw skills install melinks` (or clone into `skills/melinks/`)
- **Claude.ai**: Download zip from https://github.com/melinks/skill → Settings > Features > Add Skill
- **Claude API**: Upload via `POST /v1/skills` with beta headers `skills-2025-10-02`
- **VS Code (Copilot)**: Clone into `.github/skills/melinks/` in your project

### Skill contents

- `SKILL.md` — main entrypoint: quick-start, tool overview, auth model
- `reference/mcp-tools.md` — all 14 MCP tools with parameters and return types
- `reference/api.md` — REST API endpoints with examples
- `reference/json-format.md` — melinks v1 JSON import/export schema
- `reference/features.md` — core features reference
- `reference/pro-features.md` — Pro features reference
- `workflows/create-page.md` — create → customize → share workflow
- `workflows/manage-page.md` — update, version, rollback, delete workflows
- `workflows/analytics-ab.md` — analytics and A/B testing workflow (Pro)
- `setup/mcp-config.md` — MCP config snippets for all editors

### Source

https://github.com/melinks/skill