Към съдържанието
LinkdashLinkdash
Български
Esc
↑↓навигация↵отвори⌘Jпреглед
На тази страница

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= / JSON domain.
  • Грешки: { "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 и персонализирани домейни за тези крайни точки.

Беше ли полезна тази страница?