HTTP API
REST na https://api.linkdash.dev/v1 s klíčem bearer z dashboardu. Stejné operace jako v CLI a MCP.
Základní URL: https://api.linkdash.dev/v1
Ověření: Authorization: Bearer ldash_... (klíče vytvoříte v Dashboard → API klíče). Klíče si nevymýšlejte.
Reference CLI: CLI. MCP: MCP. Ceny / kvóty: Ceny. Discovery (bez ověření): GET https://api.linkdash.dev/v1. Čistý markdown: api.md.
Veřejná id jsou slugy (deck, k3m9xq), nikoli Convex _id. Názvy polí JSON odpovídají výstupu CLI na stdout (id, url, kind, …).
Konvence
- JSON
Content-Type: application/json, pokud není uvedeno jinak. - Vytvoření přijímá právě jedno z
url,textnebostorageId(poPOST /uploads), nebo polevariants(viz Varianty), nebo"kind": "folder"sname(viz Složky). Vygenerování vrací{ "uploadUrl", "storageId" }. Hostitel nahraje bajty metodou PUT nauploadUrl. Malé soubory mohou stále použít multipart polefilevPOST /links. - Doby trvání:
7d,24h,30m,1wnebo datum ve formátu ISO. Pole:expires/expiresAt,starts/startsAt. - Limit otevření: volitelné kladné celé číslo
maxOpenings. Odkaz se po daném počtu úspěšných otevření pozastaví. Chcete-li jej znovu zpřístupnit, zvyštemaxOpeningsnebo použijteclearMaxOpenings. Pro neomezený početmaxOpeningsvynechte. - Pokud slug existuje na dvou doménách vlastníka, předejte
?domain=/ JSONdomain. - Chyby:
{ "error": "..." }a volitelněcode. Obsazené slugylida.shvracejí409scode: "slug_taken". - Přístup: nové odkazy a složky jsou
restricted, pokud tělo nenastavíaccess(viz Přístup a sdílení).urlv odpovědích je URL pro sdílení (https://linkdash.dev/s/<token>), pokud odkaz není veřejný; u veřejného odkazu je to krátká URL. - Zápisy se započítávají do měsíční kvóty událostí (včetně sdílení, zrušení sdílení a resetu). List / get / stats / export / výpis sdílení / shared / webhook list/get se nezapočítávají. Příjem návštěv / stažení / přehrání se stále započítává.
Endpointy
| 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 (bez 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 (bez 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 z hostitele po vygenerování) | 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 a auth logout jsou toky přihlášení zařízení přes prohlížeč. Nejsou to routy Unkey.
GET /me
Přihlášený účet. { "userId": "...", "email": "...", "name": "..." }. E-mail a jméno se vynechávají, pokud nejsou známy.
Vytvoření odkazu na 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"}'
Tělo JSON přijímá právě jedno z url, text nebo storageId a dále volitelně access (výchozí restricted | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (pouze odkazy na URL) a folder (+ folderDomain) pro vytvoření uvnitř složky. Zkrácený zápis vytvoří jednu variantu s názvem main; password, starts, expires a maxOpenings na nejvyšší úrovni tvoří bránu odkazu. Odpověď: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.
GET /links vrací jednu stránku, { "items": [...], "cursor" }: ?limit= je 1–100 (výchozí 50); předávejte ?cursor= z předchozí stránky, dokud nebude null. q hledá celá slova (poslední jako prefix), seřazená podle relevance. Položky mají tvar { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (řádky složek navíc obsahují items); filtr kind přidává hodnoty folder a group, filtr status přidává mixed a folder=<slug>|root (+ folderDomain) vypíše jednu složku nebo nejvyšší úroveň. GET /links/:id vrací celý odkaz včetně access a variants; obsah (destinationUrl / textContent / fileName) je uložen u každé varianty.
Nahrání souboru
Vygenerujte URL pro nahrání ({uploadUrl,storageId}), nahrajte bajty z hostitele metodou PUT a poté ve stejném toku vytvořte odkaz:
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}'
Malé soubory mohou stále používat multipart v POST /links:
curl https://api.linkdash.dev/v1/links \
-H "Authorization: Bearer ldash_..." \
-F "file=@./deck.pdf" \
-F "expires=7d" \
-F "slug=deck"
Volitelná pole multipart: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.
Aktualizace, statistiky, CSV
PATCH /links/:id přijímá JSON nebo multipart. Bajty souboru nahradíte pomocí storageId po POST /uploads + PUT z hostitele, nebo multipart polem file (pouze u odkazů s jednou variantou). --status / { "status": "expired" } se odmítá – použijte expires. { "status": "scheduled" } se odmítá – použijte starts. Volitelné maxOpenings pozastaví odkaz po daném počtu otevření; clearMaxOpenings limit odstraní. sticky (boolean) a restartSplit (boolean) řídí přiřazování variant; forwardParams (boolean) přeposílá query string návštěvníka, viz Přeposílání parametrů dotazu. access určuje, kdo může odkaz otevřít; resetShareLink: true vydá novou URL pro sdílení. Odpověď: { "id", "url", "access", "status", "variantStatuses" }.
GET /links/:id/stats?last=24h vrací visits, downloads, plays, visitsInLast, countries, referrers, variants (součty za jednotlivé varianty), visitors a crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: boti a náhledy odkazů, které odkaz načetly; nikdy se nezapočítávají jako návštěvy; viz Protokol crawlerů).
GET /links/export vrací CSV se sloupci slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, jeden řádek na variantu (folder je slug nadřazené složky; access je restricted, link nebo public). POST /links/import přijímá surové CSV nebo multipart file; řádky se seskupují podle slugu + domény (první řádek vytvoří odkaz s jeho variantou, další řádky přidávají varianty; u existujících odkazů se aktualizují pole a poté se podle názvu aktualizují nebo přidají varianty). Řádky s kind folder (s name) vytvářejí složky a sloupec folder umístí odkazy až poté, co existují všechny řádky. Prázdné access nastaví nové odkazy jako omezené a existující odkazy ponechá beze změny.
DELETE /links/:id u složky přijímá ?contents=keep (výchozí: položky se přesunou o úroveň výš) nebo ?contents=delete (smažou se i položky a složky uvnitř).
Varianty
Každý odkaz je kontejnerem jedné či více variant: obsah (url | file | text) plus vlastní brána (password, paused, starts, expires, maxOpenings), weight a volitelné podmínky návštěvníka when. K odkazu patří slug, doména, název, štítky, náhled, vlastní brána (která má přednost před branami variant), sticky (výchozí true) a splitVersion (zvyšuje se pomocí restartSplit). Bez variants má odkaz jednu variantu s názvem main. Názvy: malá písmena, číslice, vnitřní pomlčky, 1–40 znaků, jedinečné v rámci odkazu. Nejvýše 20 variant na odkaz.
Návštěvník dostane jednu variantu: varianty, jejichž when odpovídá, tvoří fond (pokud žádná neodpovídá, tvoří jej varianty bez podmínek), poté následuje vážený výběr (sticky hash návštěvníka + odkazu + splitVersion, jinak náhodně). Crawleři dostanou první aktivní variantu bez podmínek. Odkaz s více variantami má kind group. status odkazu je stav brány odkazu, je-li nastavena, jinak stav, který sdílejí všechny varianty, jinak mixed. variantStatuses počítá { active, paused, expired, scheduled }.
Vytvoření několika variant najednou:
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"]}}]}'
Každá varianta: name (povinné), jedno z url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. Vytvoření přes multipart podporuje pouze zkrácený zápis.
| Routa | Tělo | Odpověď |
|---|---|---|
GET /links/:id/variants |
— | pole variant |
POST /links/:id/variants |
JSON nebo multipart file: name (povinné), obsah, password, starts, expires, maxOpenings, utm, weight, when |
varianta |
PATCH /links/:id/variants/:name |
name (přejmenování), url, text, storageId / file, password, clearPassword, starts, clearStarts, expires, clearExpires, maxOpenings, clearMaxOpenings, status (active | paused), weight, when, clearWhen, utm |
varianta |
DELETE /links/:id/variants/:name |
— | { "id", "variant", "deleted": true } (poslední variantu nelze smazat) |
Klíče when (pole řetězců; každý nastavený klíč musí odpovídat): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (prefix), referrerHosts (přípona hostitele).
Pravidla pro parametry dotazu
when.params je pole až 10 pravidel pro query string návštěvníka (lida.sh/promo?src=newsletter); platit musí všechna pravidla. Každé pravidlo má tvar { "key", "op", "value" }, kde op je jedno z equals | notEquals | includes | startsWith | endsWith | in (value je seznam oddělený znakem | nebo čárkami) | exists | missing. value je povinné kromě exists / missing. Klíče rozlišují velká a malá písmena, hodnoty se porovnávají přesně.
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
Hodnoty parametrů se vyhodnocují v okamžiku otevření a nikdy se neukládají do analytiky.
Přeposílání parametrů dotazu
forwardParams (boolean na odkazu, výchozí false; lze nastavit v POST /links a PATCH /links/:id, vrací jej GET /links/:id) připojí celý query string návštěvníka k variantám s URL. Hodnoty od návštěvníka přepisují uložené hodnoty, včetně utm. Varianty se souborem a textem jej ignorují. Jde o směrování, nikoli o řízení přístupu: parametry může přidat kdokoli. Hodnoty parametrů se neukládají do analytiky.
Složky
Složka je odkaz, který vypisuje položky, jež do ní vložíte. Model popisuje stránka Složky.
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_..."
| Routa | Tělo | Odpověď |
|---|---|---|
POST /links |
{ "kind": "folder", "name" } a běžná pole odkazu; bez url, text, storageId nebo variants |
vytvořená složka |
POST /links/:id/move |
{ "folder": "<slug>" } nebo { "folder": null } pro nejvyšší úroveň, volitelně folderDomain |
{ "id", "folder" } |
POST /links/:id/copy |
— | { "id", "url", "access", "kind", "variants", "folder", … } (stejný přístup, nová URL pro sdílení, bez osob) |
Přesun i kopírování se počítají každé jako jedna událost. Neznámý slug složky vrací 404 (Folder "<slug>" not found); slug, který není složkou, nebo přesun složky do sebe sama či do složky pod ní vrací 400. Složky lze vnořit nejvýše do hloubky 32.
Přístup a sdílení
Každý odkaz a každá složka má access: restricted (výchozí; vlastník a lidé, se kterými je sdílen, po přihlášení, na https://linkdash.dev/s/<token>), link (kdokoli s touto URL) nebo public (kdokoli, na krátké URL). Nastavíte jej v POST /links nebo PATCH /links/:id. U odkazů určených ke zveřejnění předejte "access": "public". Jak fungují složky a diváci, popisuje stránka Sdílení a přístup.
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_..."
| Routa | Tělo | Odpověď |
|---|---|---|
POST /links/:id/shares |
{ "emails": [...] } (1–50 e-mailů) |
{ "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" } (vše, co jste sdíleli) |
GET /shared |
— | { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" } |
DELETE /shared/:id |
— | { "_id", "left": true } (:id je _id nebo token sdílení z GET /shared) |
POST /links/:id/reset-link |
— | { "id", "access", "url" } |
POST /links/:id/shares přijímá "role": "editor" pro editory. Editoři mohou měnit položky a vidí statistiky a aktivitu, ale nikdy nemají přístup k heslům, slugu, doméně, přístupu, sdílení, mazání, přesunu ani kopírování (403); jako :id používají _id položky nebo token sdílení a varianta chráněná heslem zůstává locked: true, dokud nezavolají POST /links/:id/unlock (30 minut, deset chybných hesel za hodinu, poté 429). Uložení poté, co uložil někdo jiný, vrací 409 pouze tehdy, když požadavek posílá expectedVersion. Všechny routy sdílení přijímají ?domain=, pokud se slug opakuje. accepted je false, dokud daný e-mail nemá ověřený účet; viaFolder znamená, že přístup pochází z nadřazené složky. Nejvýše 200 osob na položku a 100 e-mailových pozvánek na účet za den. GET /shares a GET /shared vracejí výsledky po stránkách: ?limit= je 1–100 (výchozí 50); předávejte ?cursor= z předchozí stránky, dokud cursor nebude null. Sdílení, zrušení sdílení a reset se počítají každé jako jedna událost; opuštění nikoli. Přístup přes sdílenou nadřazenou složku zůstává i po opuštění.
Chyby
| Stav | Kdy |
|---|---|
| 400 | Chyba validace, chybějící tělo, smíšené druhy vytvoření |
| 401 | Chybějící nebo neplatný klíč bearer |
| 404 | Neznámý slug, doména nebo složka |
| 409 | Slug je obsazen (code: "slug_taken") |
| 429 | Dosažena měsíční kvóta událostí |
| 503 | API klíče nejsou v tomto nasazení nakonfigurovány |
Endpointy pro webhooky a vlastní domény najdete na jejich stránkách.

