# ManyLinks

> ManyLinks is a link-in-bio platform: a single shareable page (a profile plus a
> grid of blocks) that creators use to collect their links, content, and socials.
> It exposes an agent-friendly REST API and a remote MCP server so an AI agent can
> read and build a user's page directly. Create a block and it appears on the live
> page instantly.

## Overview

A ManyLinks page is a profile (username, display name, bio, avatar) plus a grid
of blocks. Block types: link, image, text, title, and map. The API and MCP server
let an agent inspect an existing page, add or edit blocks, arrange the layout, and
read analytics, with the same auth, scopes, and rate limits as the dashboard.

Link blocks pointing at a social profile (Instagram, TikTok, YouTube, X, LinkedIn,
Threads, Twitch, and more) are enriched with live data: display name, follower
count, avatar, banner, and recent posts. That data is **cached, not fetched live
at read time**. It refreshes in the background every 24 hours on Pro,
every 7 days on Free. If a refresh fails we keep serving the last known good
values rather than blanking the block.

- [Product site](https://manylinks.io)
- [API documentation](https://manylinks.io/docs/api)
- [OpenAPI spec](https://api.manylinks.io/v1/openapi.json)
- [MCP server card](https://manylinks.io/.well-known/mcp/server-card.json)

## Use cases

- Build a creator page end to end: read the profile, create link/image/text/title/map
  blocks, then arrange them on the grid.
- Keep a page in sync from another system: add, edit, or delete blocks as upstream
  content changes, and subscribe to webhooks for real-time block/profile/layout events.
- Audit performance: query dashboard-parity analytics (views, clicks, top links,
  country/device breakdowns, peak hours) for Pro pages.
- Inspect any public page by username to reproduce its structure on the caller's page.

## API

- Base URL: [https://api.manylinks.io](https://api.manylinks.io)
- [OpenAPI spec](https://api.manylinks.io/v1/openapi.json)
- [Full API docs](https://manylinks.io/docs/api)

### Auth

Pro-only. Mint an API key in Settings, then send it as a Bearer token:
`Authorization: Bearer ml_live_...`. Keys carry scopes; each endpoint needs one.
Scopes: `profile:read`, `profile:write`, `blocks:read`, `blocks:write`,
`analytics:read`, `webhooks:read`, `webhooks:write`.

Errors are RFC 9457 (`application/problem+json`). Rate limits are signaled with
`RateLimit-*` headers (and `Retry-After` on 429).

### Endpoints

- `GET /v1/health` — liveness. Public.
- `GET /v1/openapi.json` — this spec. Public.
- `GET /v1/me` — your identity, plan, and scopes. (profile:read)
- `GET /v1/profile` — your profile. (profile:read)
- `PATCH /v1/profile` — edit name/bio. (profile:write)
- `GET /v1/plan` — your plan + subscription. (profile:read)
- `GET /v1/blocks` — list your blocks, cursor-paginated, optional `?type=`. (blocks:read)
- `POST /v1/blocks` — create a block. (blocks:write)
- `GET /v1/blocks/{id}` — fetch one block. (blocks:read)
- `PATCH /v1/blocks/{id}` — edit a block's content. (blocks:write)
- `DELETE /v1/blocks/{id}` — delete a block. (blocks:write)
- `PATCH /v1/layout` — reorder blocks (desktop or mobile grid). (profile:write)
- `GET /v1/analytics?pipe=...` — dashboard-parity analytics. (analytics:read)
- `GET /v1/webhooks` — list webhook endpoints. (webhooks:read)
- `POST /v1/webhooks` — register a webhook. (webhooks:write)
- `DELETE /v1/webhooks/{id}` — delete a webhook. (webhooks:write)
- `GET /v1/pages/{username}` — a public page (profile + blocks). Public, no key.

### Pagination

List endpoints return `{ data, nextCursor, hasMore }`. Pass `nextCursor` back as
`?cursor=` until `hasMore` is false.

## MCP server

A remote MCP server lets Claude, Cursor, and other clients connect over Streamable
HTTP and build a page directly. Auth is the same Bearer API key as the REST API.

- Endpoint: `https://manylinks.io/api/mcp`
- [Server card](https://manylinks.io/.well-known/mcp/server-card.json)
- Tools: get_my_profile, list_blocks, get_block, create_block, update_block,
  delete_block, update_layout, update_profile, get_analytics, list_webhooks,
  create_webhook, delete_webhook, get_page.

## Constraints

- Pro-only: the API and MCP writes/reads require a ManyLinks Pro plan. Building a
  page (profile / blocks / layout) works on a free account via MCP; analytics and
  webhooks require Pro.
- Versioning: the major version is in the path (`/v1`). Breaking changes ship a new
  major; `/v1` keeps working through a deprecation window.
- Media uploads (avatars, block images) are UI-only for now; the API sets metadata
  and resolved URLs are returned as `image_url` / `favicon_url` etc.
- Social enrichment is asynchronous and cached. Creating a social link block returns
  immediately; follower counts and avatars appear once the background fetch lands,
  usually within a minute. Do not poll expecting instant values. Each block reports
  `dataUpdatedAt`, the timestamp of the last successful refresh, so a client can
  reason about freshness instead of guessing.
- Webhook URLs must be public HTTPS (no localhost / private IPs); the signing secret
  is shown once at creation.