---
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](/bg/cli). MCP: [MCP](/bg/mcp). Цени / квоти: [Цени](/bg/pricing). Откриване (без удостоверяване): `GET https://api.linkdash.dev/v1`. Обикновен markdown: [api.md](https://linkdash.dev/api.md).

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

## Конвенции

- JSON с `Content-Type: application/json`, освен ако не е посочено друго.
- Създаването приема точно едно от `url`, `text` или `storageId` след `POST /uploads`, **или** масив `variants` (вижте [Варианти](#variants)), **или** `"kind": "folder"` с `name` (вижте [Папки](#folders)). Генерирането връща `{ "uploadUrl", "storageId" }`. Хостът изпраща байтовете с PUT към `uploadUrl`. Малките файлове все още могат да използват multipart поле `file` в `POST /links`.
- Продължителности: `7d`, `24h`, `30m`, `1w` или ISO дата. Полета: `expires` / `expiresAt`, `starts` / `startsAt`.
- Лимит на отварянията: незадължително положително цяло число `maxOpenings`. Връзката се поставя на пауза след толкова успешни отваряния. Увеличете `maxOpenings` или използвайте `clearMaxOpenings`, за да започне да се обслужва отново. Пропуснете `maxOpenings` за неограничен брой.
- Ако даден slug съществува в два от домейните на собственика, подайте `?domain=` / JSON `domain`.
- Грешки: `{ "error": "..." }` плюс незадължителен `code`. Заетите slug-ове в `lida.sh` връщат `409` с `code: "slug_taken"`.
- Достъп: новите връзки и папки са `restricted`, освен ако тялото на заявката не задава `access` (вижте [Достъп и споделяне](#access-and-sharing)). `url` в отговорите е URL адресът за споделяне (`https://linkdash.dev/s/<token>`), освен ако връзката не е публична — тогава е краткият URL.
- Записите се отчитат към месечната квота за събития (включително споделяне, премахване на споделяне и нулиране). List / get / stats / export / списъкът със споделяния / shared / webhook list/get не се отчитат. Регистрирането на посещения / изтегляния / възпроизвеждания все пак се отчита.

## Крайни точки

| 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 от хоста след генериране) | `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": "..." }`. Имейлът и името се пропускат, когато не са известни.

## Създаване на 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` е slug на съдържащата папка; `access` е `restricted`, `link` или `public`). `POST /links/import` приема суров CSV или multipart `file`; редовете се групират по slug + домейн (първият ред създава връзката с нейния вариант, следващите редове добавят варианти; при съществуващи връзки се обновяват полетата, след което вариантите се обновяват или добавят по име). Редовете с `kind` `folder` (с `name`) създават папки, а колоната `folder` поставя връзките в тях, след като всички редове бъдат създадени. Празно `access` прави новите връзки с ограничен достъп и оставя съществуващите връзки непроменени.

`DELETE /links/:id` за папка приема `?contents=keep` (по подразбиране: елементите се преместват едно ниво нагоре) или `?contents=delete` (елементите и папките в нея също се изтриват).

## Варианти

Всяка връзка е контейнер за един или повече **варианти**: съдържание (`url` | `file` | `text`) плюс собствени ограничения (`password`, `paused`, `starts`, `expires`, `maxOpenings`), `weight` и незадължителни условия за посетителя `when`. На връзката принадлежат slug, домейн, име, тагове, визуализация, собствените ѝ ограничения (които имат предимство пред ограниченията на вариантите), `sticky` (по подразбиране `true`) и `splitVersion` (увеличава се от `restartSplit`). Без `variants` връзката има един вариант с име `main`. Имена: малки букви, цифри, вътрешни тирета, 1–40 знака, уникални в рамките на връзката. Най-много 20 варианта на връзка.

Посетителят получава един вариант: вариантите, чието `when` съвпада, формират набора (ако няма съвпадения, се използват безусловните варианти), след което се прави претеглен избор (sticky хеш на посетителя + връзката + `splitVersion`, в противен случай случаен). Краулърите получават първия активен безусловен вариант. `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`. Файловите и текстовите варианти го игнорират. Това е маршрутизиране, а не контрол на достъпа: всеки може да добави параметри. Стойностите на параметрите не се съхраняват в аналитиката.

## Папки

Папката е връзка, която изброява елементите, които сте поставили в нея. Вижте [Папки](/bg/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 за споделяне, без хора) |

Преместването и копирането се отчитат като по едно събитие. Неизвестен slug на папка връща `404` (`Folder "<slug>" not found`); slug, който не е папка, или преместване на папка в самата нея или в папка под нея връща `400`. Папките могат да се влагат най-много на 32 нива.

## Достъп и споделяне

Всяка връзка и папка има `access`: `restricted` (по подразбиране; собственикът и хората, с които е споделена, след вход, на `https://linkdash.dev/s/<token>`), `link` (всеки с този URL) или `public` (всеки, на краткия URL). Задайте го в `POST /links` или `PATCH /links/:id`. Подайте `"access": "public"` за връзки, предназначени за публично публикуване. Вижте [Споделяне и достъп](/bg/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"` за редактори. Редакторите могат да променят елементи и да виждат статистиката и активността, но нямат достъп до пароли, slug, домейн, достъп, споделяне, изтриване, преместване или копиране (`403`); те използват `_id` на елемента или токена за споделяне като `:id`, а защитен с парола вариант остава `locked: true` до `POST /links/:id/unlock` (30 минути, десет грешни пароли на час, след което `429`). Запазване, след като някой друг вече е запазил, връща `409` само когато заявката изпраща `expectedVersion`. Всички маршрути за споделяне приемат `?domain=`, когато slug се повтаря. `accepted` е `false`, докато този имейл няма потвърден акаунт; `viaFolder` означава, че достъпът идва от папка по-горе. До 200 души на елемент и 100 имейла с покани на акаунт на ден. `GET /shares` и `GET /shared` връщат по една страница: `?limit=` е от 1 до 100 (по подразбиране 50); подавайте `?cursor=` от предишната страница, докато `cursor` не стане `null`. Споделянето, премахването на споделянето и нулирането се отчитат като по едно събитие; напускането — не. Достъпът чрез споделена папка по-горе се запазва и след напускане.

## Грешки

| Статус | Кога |
| --- | --- |
| 400 | Грешка при валидиране, липсващо тяло, смесени видове създаване |
| 401 | Липсващ или невалиден bearer ключ |
| 404 | Неизвестен slug, домейн или папка |
| 409 | Slug е зает (`code: "slug_taken"`) |
| 429 | Достигната е месечната квота за събития |
| 503 | API ключовете не са конфигурирани в това внедряване |

Вижте [webhooks](/bg/webhooks) и [персонализирани домейни](/bg/domains) за тези крайни точки.
