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.
Публичните идентификатори са slug-ове (deck, k3m9xq), а не Convex _id. Имената на JSON полетата съвпадат със stdout на CLI (id, url, kind, …).
Конвенции
- JSON с
Content-Type: application/json, освен ако не е посочено друго. - Създаването приема точно едно от
url,textилиstorageIdследPOST /uploads, или масивvariants(вижте Варианти), или"kind": "folder"сname(вижте Папки). Генерирането връща{ "uploadUrl", "storageId" }. Хостът изпраща байтовете с PUT къмuploadUrl. Малките файлове все още могат да използват multipart полеfileвPOST /links. - Продължителности:
7d,24h,30m,1wили ISO дата. Полета:expires/expiresAt,starts/startsAt. - Лимит на отварянията: незадължително положително цяло число
maxOpenings. Връзката се поставя на пауза след толкова успешни отваряния. УвеличетеmaxOpeningsили използвайтеclearMaxOpenings, за да започне да се обслужва отново. ПропуснетеmaxOpeningsза неограничен брой. - Ако даден slug съществува в два от домейните на собственика, подайте
?domain=/ JSONdomain. - Грешки:
{ "error": "..." }плюс незадължителенcode. Заетите slug-ове вlida.shвръщат409сcode: "slug_taken". - Достъп: новите връзки и папки са
restricted, освен ако тялото на заявката не задаваaccess(вижте Достъп и споделяне).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" } |
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 връзка
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 е 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 }.
Създаване на няколко варианта наведнъж:
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 за споделяне, без хора) |
Преместването и копирането се отчитат като по едно събитие. Неизвестен 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" за връзки, предназначени за публично публикуване. Вижте Споделяне и достъп, за да разберете как работят папките и зрителите.
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 и персонализирани домейни за тези крайни точки.

