# Liinks

> Liinks is a link-in-bio platform. Users build a public profile page made up of links, text, media, embeds, social icons, FAQs, testimonials, and other blocks. The Liinks Public API lets users — and AI agents acting on their behalf — programmatically create and manage profiles, blocks, and styles.

The Public API is a versioned REST API at `https://www.liinks.co/api/v1`, authenticated by Bearer API keys. Validation is strict, errors are structured, and the OpenAPI 3.1 specification is the canonical contract — read it before generating clients.

The API is currently in beta. Endpoints, field shapes, and validation rules may change with notice.

## API

- [OpenAPI specification](https://www.liinks.co/api/openapi.json): Machine-readable contract for every endpoint, generated from server schemas. Always current. Start here.
- [Interactive docs](https://www.liinks.co/api/docs): Browsable reference rendered from the OpenAPI spec.
- [API root](https://www.liinks.co/api/v1): Discovery payload listing the spec and docs URLs.

## Authentication

All `/api/v1/*` endpoints require `Authorization: Bearer liinks_live_<token>`. Tokens are created under Account → API Keys in the Liinks dashboard. A paid Liinks plan is required; accounts without one receive `402 plan_required`. Creating new managed profiles (`POST /profiles`) additionally requires a plan that supports managing multiple profiles.

Per-key rate limits: 120 requests/minute global, 30 writes/minute. On limit, expect `429 rate_limited` with `error.details.retryAfterSeconds`.

## Resources

- **Profiles** — a Liinks page. `GET/POST /api/v1/profiles`, `GET/PATCH/DELETE /api/v1/profiles/{id}`. Creating a new profile requires a multi-profile plan.
- **Styles** — theme (colors, fonts, background, button styling). `GET/PATCH /api/v1/profiles/{id}/styles`.
- **Blocks** — building blocks of a profile (`link`, `text`, `divider`, `folder`, `media`). `GET/POST /api/v1/profiles/{id}/blocks`, `GET/PATCH/DELETE /api/v1/profiles/{id}/blocks/{blockId}`, `POST /api/v1/profiles/{id}/blocks/reorder` (must include all block IDs on the page).

Block payloads are a discriminated union on `type`. Use `PATCH` to hide, move between pages, or move into folders — there are no dedicated `/hide`, `/move` verbs.

## Errors

Every error returns `{ "error": { "code", "message", "details?" } }`. Common codes: `validation_error` (400, includes a Zod `issues` tree agents can read to self-correct), `unauthorized` (401), `plan_required` (402), `forbidden` (403), `not_found` (404), `conflict` (409), `rate_limited` (429). Unknown input fields are rejected.

## Contact

API feedback or bug reports: hello@liinks.co.

## Optional

- [Help center](https://www.liinks.co/help): Product documentation for human users of Liinks.
- [robots.txt](https://www.liinks.co/robots.txt), [sitemap.xml](https://www.liinks.co/sitemap.xml).