HTTP API
REST по адресу https://api.linkdash.dev/v1 с bearer-ключом из панели управления. Те же операции, что в CLI и MCP.
Базовый URL: https://api.linkdash.dev/v1
Аутентификация: Authorization: Bearer ldash_... (ключи создаются в разделе Панель управления → API-ключи). Не придумывайте ключи.
Справочник по CLI: CLI. MCP: MCP. Цены и квоты: Цены. Обнаружение (без аутентификации): GET https://api.linkdash.dev/v1. Обычный markdown: api.md.
Публичные идентификаторы — это слаги (deck, k3m9xq), а не Convex _id. Имена полей JSON совпадают с выводом CLI в stdout (id, url, kind, …).
Соглашения
- JSON
Content-Type: application/json, если не указано иное. - При создании передаётся ровно одно из полей
url,textилиstorageId(послеPOST /uploads), или массивvariants(см. Варианты), или"kind": "folder"сname(см. Папки). Запрос на получение URL загрузки возвращает{ "uploadUrl", "storageId" }. Хост отправляет байты через PUT наuploadUrl. Небольшие файлы по-прежнему можно передавать в multipart-полеfileвPOST /links. - Длительности:
7d,24h,30m,1wили дата в формате ISO. Поля:expires/expiresAt,starts/startsAt. - Лимит открытий: необязательное положительное целое число
maxOpenings. Ссылка приостанавливается после указанного количества успешных открытий. Чтобы ссылка снова заработала, увеличьтеmaxOpeningsили передайтеclearMaxOpenings. ЕслиmaxOpeningsне указан, количество открытий не ограничено. - Если слаг существует на двух доменах владельца, передайте
?domain=/ поле JSONdomain. - Ошибки:
{ "error": "..." }и необязательныйcode. Для занятых слаговlida.shвозвращается409сcode: "slug_taken". - Доступ: новые ссылки и папки создаются с доступом
restricted, если в теле запроса не заданоaccess(см. Доступ и общий доступ).urlв ответах — это URL для общего доступа (https://linkdash.dev/s/<token>), а для публичных ссылок — короткий URL. - Операции записи учитываются в месячной квоте событий (включая предоставление доступа, отзыв доступа и сброс ссылки). Получение списка, получение ссылки, статистика, экспорт, список участников, список доступных вам элементов, а также получение списка и отдельных вебхуков не учитываются. Регистрация посещений, скачиваний и воспроизведений по-прежнему учитывается.
Эндпоинты
| CLI | HTTP | MCP |
|---|---|---|
auth whoami |
GET /me |
whoami |
links list |
GET /links (?q=&tag=&kind=&status=&folder=&limit=&cursor=) |
links_list |
links get <id> |
GET /links/:id (?domain=) |
links_get |
links create --url/--file/--text/--folder |
POST /links |
links_create |
links update <id> |
PATCH /links/:id |
links_update |
links move <id> |
POST /links/:id/move |
links_move |
links copy <id> |
POST /links/:id/copy |
links_copy |
links delete <id> |
DELETE /links/:id (?contents=keep|delete) |
links_delete |
links share <id> --email <e> |
POST /links/:id/shares |
links_share |
links unshare <id> --email <e> |
DELETE /links/:id/shares/:email |
links_unshare |
links shares <id> |
GET /links/:id/shares |
links_shares |
links shares (без id) |
PATCH /links/:id/shares/:email |
{ "role": "viewer" | "editor" } |
POST /links/:id/unlock |
{ "variant"?, "password"?, "variantPassword"? } |
{ "_id", "variant", "unlocked": true, "minutes": 30, ...target } |
GET /links/:id/activity |
— | { "items": [{ "_id", "_creationTime", "action", "detail"?, "actor" }], "cursor" } |
GET /shares |
links_shares (без id) |
|
links shared |
GET /shared |
links_shared |
links leave <_id | share URL> |
DELETE /shared/:id |
links_leave |
links role <id> --email <e> --role viewer|editor |
PATCH /links/:id/shares/:email |
links_share_role |
links unlock <_id | share URL> |
POST /links/:id/unlock |
links_unlock |
links activity <id> |
GET /links/:id/activity |
links_activity |
links reset-link <id> |
POST /links/:id/reset-link |
links_update (resetShareLink: true) |
links stats --last 24h |
GET /links/:id/stats?last=24h |
links_stats |
links export |
GET /links/export |
links_export |
links import |
POST /links/import |
links_import |
links variants list <id> |
GET /links/:id/variants |
variants_list |
links variants add <id> |
POST /links/:id/variants |
variants_add |
links variants update <id> <name> |
PATCH /links/:id/variants/:name |
variants_update |
links variants remove <id> <name> |
DELETE /links/:id/variants/:name |
variants_remove |
| (PUT с хоста после получения URL загрузки) | POST /uploads |
files_upload_url |
DELETE /uploads/:storageId |
files_discard |
|
webhooks list/create/get/rotate/delete |
GET/POST /webhooks, GET/DELETE /webhooks/:id, POST /webhooks/:id/rotate |
webhooks_* |
domains list/add/connect/verify/remove |
GET/POST /domains, GET /domains/:host/connect, POST /domains/:host/verify, DELETE /domains/:host |
domains_* |
auth create, auth login и auth logout — это браузерные процессы авторизации устройства. Это не маршруты Unkey.
GET /me
Аккаунт, под которым выполнен вход. { "userId": "...", "email": "...", "name": "..." }. Email и имя не возвращаются, если они неизвестны.
Создание ссылки на URL
curl https://api.linkdash.dev/v1/links \
-H "Authorization: Bearer ldash_..." \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com","slug":"welcome","access":"public"}'
Тело JSON содержит ровно одно из полей url, text или storageId, а также необязательные access (restricted по умолчанию | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (только для ссылок на URL) и folder (+ folderDomain) для создания ссылки внутри папки. Сокращённая форма создаёт один вариант с именем main; поля верхнего уровня password, starts, expires и maxOpenings задают ограничения на уровне ссылки. Ответ: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.
GET /links возвращает одну страницу, { "items": [...], "cursor" }: ?limit= — от 1 до 100 (по умолчанию 50); передавайте ?cursor= из предыдущей страницы, пока он не станет null. q ищет по целым словам (последнее слово — как префикс), результаты ранжируются по релевантности. Элементы имеют вид { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (у строк папок добавляется items); фильтр kind дополнительно поддерживает folder и group, фильтр status — mixed, а folder=<slug>|root (+ folderDomain) выводит содержимое одной папки или верхнего уровня. GET /links/:id возвращает полную ссылку с access и variants; содержимое (destinationUrl / textContent / fileName) хранится в каждом варианте.
Загрузка файла
Получите URL загрузки ({uploadUrl,storageId}), отправьте байты через PUT с хоста, затем создайте ссылку в рамках того же процесса:
curl https://api.linkdash.dev/v1/uploads \
-H "Authorization: Bearer ldash_..." \
-H "Content-Type: application/json" \
-d '{"fileSize":12345}'
curl -X PUT -H "Content-Type: application/pdf" --data-binary @./deck.pdf "$uploadUrl"
curl https://api.linkdash.dev/v1/links \
-H "Authorization: Bearer ldash_..." \
-H "Content-Type: application/json" \
-d '{"storageId":"…","fileName":"deck.pdf","fileType":"application/pdf","fileSize":12345}'
Небольшие файлы по-прежнему можно передавать через multipart в POST /links:
curl https://api.linkdash.dev/v1/links \
-H "Authorization: Bearer ldash_..." \
-F "file=@./deck.pdf" \
-F "expires=7d" \
-F "slug=deck"
Необязательные multipart-поля: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.
Обновление, статистика, CSV
PATCH /links/:id принимает JSON или multipart. Чтобы заменить содержимое файла, передайте storageId после POST /uploads и PUT с хоста или multipart-поле file (только для ссылок с одним вариантом). --status / { "status": "expired" } отклоняется — используйте expires. { "status": "scheduled" } отклоняется — используйте starts. Необязательный maxOpenings приостанавливает ссылку после указанного количества открытий; clearMaxOpenings снимает ограничение. sticky (boolean) и restartSplit (boolean) управляют назначением вариантов; forwardParams (boolean) передаёт строку запроса посетителя, см. Передача параметров запроса. access определяет, кто может открыть ссылку; resetShareLink: true выпускает новый URL для общего доступа. Ответ: { "id", "url", "access", "status", "variantStatuses" }.
GET /links/:id/stats?last=24h возвращает visits, downloads, plays, visitsInLast, countries, referrers, variants (итоги по каждому варианту), visitors и crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: боты и сервисы предпросмотра ссылок, которые запрашивали ссылку; они никогда не учитываются как посещения; см. Журнал краулеров).
GET /links/export возвращает CSV со столбцами slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, по одной строке на вариант (folder — слаг родительской папки; access — restricted, link или public). POST /links/import принимает необработанный CSV или multipart-поле file; строки группируются по слагу и домену (первая строка создаёт ссылку с её вариантом, последующие добавляют варианты; у существующих ссылок обновляются поля, затем варианты обновляются или добавляются по имени). Строки с kind folder (и name) создают папки, а столбец folder размещает ссылки по папкам после того, как созданы все строки. Пустое access делает новые ссылки ограниченными и не меняет существующие.
DELETE /links/:id для папки принимает ?contents=keep (по умолчанию: элементы перемещаются на уровень выше) или ?contents=delete (вложенные элементы и папки тоже удаляются).
Варианты
Каждая ссылка — это контейнер для одного или нескольких вариантов: содержимое (url | file | text) плюс собственные ограничения (password, paused, starts, expires, maxOpenings), вес weight и необязательные условия для посетителей when. Ссылке принадлежат слаг, домен, имя, теги, предпросмотр, собственные ограничения (имеют приоритет над ограничениями вариантов), sticky (по умолчанию true) и splitVersion (увеличивается при restartSplit). Без variants у ссылки есть один вариант с именем main. Имена: строчные буквы, цифры и дефисы внутри имени, от 1 до 40 символов, уникальные в пределах ссылки. Не более 20 вариантов на ссылку.
Посетитель получает один вариант: варианты, чьё условие when совпадает, образуют пул (если совпадений нет, пул составляют варианты без условий), затем выполняется взвешенный выбор (по стабильному хешу посетителя, ссылки и splitVersion при sticky, иначе случайно). Краулеры получают первый активный вариант без условий. kind ссылки с несколькими вариантами — group. status ссылки — это статус ограничений ссылки, если они заданы, иначе общий статус всех вариантов, иначе mixed. variantStatuses содержит счётчики { active, paused, expired, scheduled }.
Создание нескольких вариантов сразу:
curl https://api.linkdash.dev/v1/links \
-H "Authorization: Bearer ldash_..." \
-H "Content-Type: application/json" \
-d '{"slug":"promo","variants":[{"name":"a","url":"https://example.com/a"},{"name":"b","url":"https://example.com/b","weight":3,"when":{"countries":["DE","AT"]}}]}'
Поля каждого варианта: name (обязательно), одно из url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. Создание через multipart поддерживает только сокращённую форму.
| Маршрут | Тело | Ответ |
|---|---|---|
GET /links/:id/variants |
— | массив вариантов |
POST /links/:id/variants |
JSON или multipart file: name (обязательно), содержимое, password, starts, expires, maxOpenings, utm, weight, when |
вариант |
PATCH /links/:id/variants/:name |
name (переименование), url, text, storageId / file, password, clearPassword, starts, clearStarts, expires, clearExpires, maxOpenings, clearMaxOpenings, status (active | paused), weight, when, clearWhen, utm |
вариант |
DELETE /links/:id/variants/:name |
— | { "id", "variant", "deleted": true } (последний вариант удалить нельзя) |
Ключи when (массивы строк; должны совпасть все заданные ключи): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (префикс), referrerHosts (суффикс хоста).
Правила для параметров запроса
when.params — это массив из не более чем 10 правил для строки запроса посетителя (lida.sh/promo?src=newsletter); должны выполняться все правила. Каждое правило имеет вид { "key", "op", "value" }, где op — одно из equals | notEquals | includes | startsWith | endsWith | in (value — список, разделённый | или запятыми) | exists | missing. value обязательно для всех операторов, кроме exists / missing. Ключи чувствительны к регистру, значения сравниваются точно.
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
Значения параметров сопоставляются в момент открытия и никогда не сохраняются в аналитике.
Передача параметров запроса
forwardParams (boolean на уровне ссылки, по умолчанию false; задаётся в POST /links и PATCH /links/:id, возвращается в GET /links/:id) добавляет всю строку запроса посетителя к вариантам с URL. Значения посетителя перезаписывают сохранённые, включая utm. Варианты с файлами и текстом его игнорируют. Это механизм маршрутизации, а не контроля доступа: добавить параметры может кто угодно. Значения параметров не сохраняются в аналитике.
Папки
Папка — это ссылка, которая выводит список помещённых в неё элементов. Описание модели см. в разделе Папки.
curl https://api.linkdash.dev/v1/links \
-H "Authorization: Bearer ldash_..." \
-H "Content-Type: application/json" \
-d '{"kind":"folder","name":"Q4 launch","slug":"q4"}'
curl https://api.linkdash.dev/v1/links \
-H "Authorization: Bearer ldash_..." \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/deck","folder":"q4"}'
curl https://api.linkdash.dev/v1/links/k3m9xq/move \
-H "Authorization: Bearer ldash_..." \
-H "Content-Type: application/json" \
-d '{"folder":"q4"}'
curl "https://api.linkdash.dev/v1/links?folder=q4" -H "Authorization: Bearer ldash_..."
| Маршрут | Тело | Ответ |
|---|---|---|
POST /links |
{ "kind": "folder", "name" } и обычные поля ссылки; без url, text, storageId и variants |
созданная папка |
POST /links/:id/move |
{ "folder": "<slug>" } или { "folder": null } для верхнего уровня, необязательный folderDomain |
{ "id", "folder" } |
POST /links/:id/copy |
— | { "id", "url", "access", "kind", "variants", "folder", … } (тот же уровень доступа, новый URL для общего доступа, без участников) |
Перемещение и копирование учитываются как одно событие каждое. Для неизвестного слага папки возвращается 404 (Folder "<slug>" not found); если слаг не является папкой или папка перемещается в саму себя либо во вложенную в неё папку, возвращается 400. Максимальная глубина вложенности папок — 32.
Доступ и общий доступ
У каждой ссылки и папки есть access: restricted (по умолчанию; владелец и пользователи, которым предоставлен доступ, после входа в аккаунт, по адресу https://linkdash.dev/s/<token>), link (любой, у кого есть этот URL) или public (любой, по короткому URL). Задаётся в POST /links или PATCH /links/:id. Для ссылок, которые предназначены для публичного размещения, передавайте "access": "public". Как работают папки и просматривающие пользователи, описано в разделе Общий доступ и права.
curl https://api.linkdash.dev/v1/links/q4/shares \
-H "Authorization: Bearer ldash_..." \
-H "Content-Type: application/json" \
-d '{"emails":["anna@example.com","ben@example.com"]}'
curl https://api.linkdash.dev/v1/links/q4/shares -H "Authorization: Bearer ldash_..."
curl -X DELETE https://api.linkdash.dev/v1/links/q4/shares/ben%40example.com -H "Authorization: Bearer ldash_..."
curl -X POST https://api.linkdash.dev/v1/links/q4/reset-link -H "Authorization: Bearer ldash_..."
curl https://api.linkdash.dev/v1/shares -H "Authorization: Bearer ldash_..."
curl -X DELETE https://api.linkdash.dev/v1/shared/<_id> -H "Authorization: Bearer ldash_..."
| Маршрут | Тело | Ответ |
|---|---|---|
POST /links/:id/shares |
{ "emails": [...] } (от 1 до 50 адресов) |
{ "id", "url", "access", "invited", "alreadyShared" } |
DELETE /links/:id/shares/:email |
— | { "id", "email", "removed": true } |
GET /links/:id/shares |
— | [{ "email", "role": "viewer", "accepted", "invitedAt", "viaFolder"?: { "id", "name"?, "slug" } }] |
GET /shares |
— | { "items": [{ "id", "name"?, "kind", "access", "url", "people": [{ "email", "accepted", "invitedAt" }] }], "cursor" } (всё, к чему вы предоставили доступ) |
GET /shared |
— | { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" } |
DELETE /shared/:id |
— | { "_id", "left": true } (:id — это _id или токен общего доступа из GET /shared) |
POST /links/:id/reset-link |
— | { "id", "access", "url" } |
POST /links/:id/shares принимает "role": "editor" для редакторов. Редакторы могут изменять элементы и видят статистику и журнал действий, но не имеют доступа к паролям, слагу, домену, настройкам доступа, общему доступу, удалению, перемещению и копированию (403); в качестве :id они используют _id элемента или токен общего доступа, а защищённый паролем вариант остаётся в состоянии locked: true до вызова POST /links/:id/unlock (на 30 минут; не более десяти неверных паролей в час, затем 429). Сохранение после того, как кто-то другой уже сохранил изменения, возвращает 409, только если в запросе передан expectedVersion. Все маршруты общего доступа принимают ?domain=, если слаг повторяется. accepted имеет значение false, пока у владельца этого email нет подтверждённого аккаунта; viaFolder означает, что доступ унаследован от вышестоящей папки. Не более 200 участников на элемент и 100 писем с приглашениями на аккаунт в день. GET /shares и GET /shared возвращают результаты постранично: ?limit= — от 1 до 100 (по умолчанию 50); передавайте ?cursor= из предыдущей страницы, пока cursor не станет null. Предоставление доступа, отзыв доступа и сброс ссылки учитываются как одно событие каждое; выход из общего доступа не учитывается. Доступ через вышестоящую папку с общим доступом после выхода сохраняется.
Ошибки
| Статус | Когда |
|---|---|
| 400 | Ошибка валидации, отсутствует тело запроса, смешаны типы создания |
| 401 | Bearer-ключ отсутствует или недействителен |
| 404 | Неизвестный слаг, домен или папка |
| 409 | Слаг занят (code: "slug_taken") |
| 429 | Достигнута месячная квота событий |
| 503 | API-ключи не настроены в этом развёртывании |
Описание соответствующих эндпоинтов см. в разделах Вебхуки и Пользовательские домены.

