---
title: HTTP API
description: >-
  REST по адресу https://api.linkdash.dev/v1 с bearer-ключом из панели
  управления. Те же операции, что в CLI и MCP.
sidebar:
  label: HTTP API
  order: 4
---
Базовый URL: `https://api.linkdash.dev/v1`

Аутентификация: `Authorization: Bearer ldash_...` (ключи создаются в разделе [Панель управления → API-ключи](https://linkdash.dev/dashboard/keys)). Не придумывайте ключи.

Справочник по CLI: [CLI](/ru/cli). MCP: [MCP](/ru/mcp). Цены и квоты: [Цены](/ru/pricing). Обнаружение (без аутентификации): `GET https://api.linkdash.dev/v1`. Обычный markdown: [api.md](https://linkdash.dev/api.md).

Публичные идентификаторы — это слаги (`deck`, `k3m9xq`), а не Convex `_id`. Имена полей JSON совпадают с выводом CLI в stdout (`id`, `url`, `kind`, …).

## Соглашения

- JSON `Content-Type: application/json`, если не указано иное.
- При создании передаётся ровно одно из полей `url`, `text` или `storageId` (после `POST /uploads`), **или** массив `variants` (см. [Варианты](#variants)), **или** `"kind": "folder"` с `name` (см. [Папки](#folders)). Запрос на получение URL загрузки возвращает `{ "uploadUrl", "storageId" }`. Хост отправляет байты через PUT на `uploadUrl`. Небольшие файлы по-прежнему можно передавать в multipart-поле `file` в `POST /links`.
- Длительности: `7d`, `24h`, `30m`, `1w` или дата в формате ISO. Поля: `expires` / `expiresAt`, `starts` / `startsAt`.
- Лимит открытий: необязательное положительное целое число `maxOpenings`. Ссылка приостанавливается после указанного количества успешных открытий. Чтобы ссылка снова заработала, увеличьте `maxOpenings` или передайте `clearMaxOpenings`. Если `maxOpenings` не указан, количество открытий не ограничено.
- Если слаг существует на двух доменах владельца, передайте `?domain=` / поле JSON `domain`.
- Ошибки: `{ "error": "..." }` и необязательный `code`. Для занятых слагов `lida.sh` возвращается `409` с `code: "slug_taken"`.
- Доступ: новые ссылки и папки создаются с доступом `restricted`, если в теле запроса не задано `access` (см. [Доступ и общий доступ](#access-and-sharing)). `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" }` | `{ "id", "email", "role" }` |
| `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

```bash
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 с хоста, затем создайте ссылку в рамках того же процесса:

```bash
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`:

```bash
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) передаёт строку запроса посетителя, см. [Передача параметров запроса](#forward-query-parameters). `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" }]`: боты и сервисы предпросмотра ссылок, которые запрашивали ссылку; они никогда не учитываются как посещения; см. [Журнал краулеров](https://linkdash.dev/pricing.md)).

`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 }`.

Создание нескольких вариантов сразу:

```bash
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`. Ключи чувствительны к регистру, значения сравниваются точно.

```json
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
```

Значения параметров сопоставляются в момент открытия и никогда не сохраняются в аналитике.

### Передача параметров запроса

`forwardParams` (boolean на уровне ссылки, по умолчанию `false`; задаётся в `POST /links` и `PATCH /links/:id`, возвращается в `GET /links/:id`) добавляет всю строку запроса посетителя к вариантам с URL. Значения посетителя перезаписывают сохранённые, включая `utm`. Варианты с файлами и текстом его игнорируют. Это механизм маршрутизации, а не контроля доступа: добавить параметры может кто угодно. Значения параметров не сохраняются в аналитике.

## Папки

Папка — это ссылка, которая выводит список помещённых в неё элементов. Описание модели см. в разделе [Папки](/ru/folders).

```bash
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"`. Как работают папки и просматривающие пользователи, описано в разделе [Общий доступ и права](/ru/sharing).

```bash
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-ключи не настроены в этом развёртывании |

Описание соответствующих эндпоинтов см. в разделах [Вебхуки](/ru/webhooks) и [Пользовательские домены](/ru/domains).
