HTTP API
REST na https://api.linkdash.dev/v1 s bearer kľúčom z dashboardu. Rovnaké operácie ako v CLI a MCP.
Základná URL: https://api.linkdash.dev/v1
Overenie: Authorization: Bearer ldash_... (kľúče vytvoríte v Dashboard → API kľúče). Kľúče si nevymýšľajte.
Referencia CLI: CLI. MCP: MCP. Ceny / kvóty: Ceny. Discovery (bez overenia): GET https://api.linkdash.dev/v1. Čistý markdown: api.md.
Verejné identifikátory sú slugy (deck, k3m9xq), nie Convex _id. Názvy polí v JSON zodpovedajú výstupu CLI na stdout (id, url, kind, …).
Konvencie
- JSON
Content-Type: application/json, ak nie je uvedené inak. - Vytvorenie prijíma presne jedno z
url,textalebostorageIdpoPOST /uploads, alebo polevariants(pozri Varianty), alebo"kind": "folder"sname(pozri Priečinky). Vygenerovanie URL na nahratie vracia{ "uploadUrl", "storageId" }. Hostiteľ odošle bajty cez PUT nauploadUrl. Malé súbory môžu stále použiť multipartfilenaPOST /links. - Trvania:
7d,24h,30m,1walebo dátum ISO. Polia:expires/expiresAt,starts/startsAt. - Limit otvorení: voliteľné kladné celé číslo
maxOpenings. Odkaz sa pozastaví po danom počte úspešných otvorení. Ak ho chcete znova sprístupniť, zvýštemaxOpeningsalebo použiteclearMaxOpenings. Pre neobmedzený početmaxOpeningsvynechajte. - Ak slug existuje na dvoch doménach vlastníka, odovzdajte
?domain=/ JSONdomain. - Chyby:
{ "error": "..." }plus voliteľnýcode. Obsadené slugylida.shvracajú409scode: "slug_taken". - Prístup: nové odkazy a priečinky sú
restricted, pokiaľ telo nenastavíaccess(pozri Prístup a zdieľanie).urlv odpovediach je URL na zdieľanie (https://linkdash.dev/s/<token>), okrem prípadu, keď je odkaz verejný – vtedy je to krátka URL. - Zápisy sa započítavajú do mesačnej kvóty udalostí (vrátane zdieľania, zrušenia zdieľania a resetu). List / get / stats / export / zoznam zdieľaní / shared / webhook list/get sa nezapočítavajú. Príjem návštev / stiahnutí / prehratí sa stále započítava.
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 hostiteľa po vygenerovaní 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 a auth logout sú device flow v prehliadači. Nie sú to trasy Unkey.
GET /me
Prihlásený účet. { "userId": "...", "email": "...", "name": "..." }. E-mail a meno sa vynechajú, ak nie sú známe.
Vytvorenie URL odkazu
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"}'
Telo JSON prijíma presne jedno z url, text alebo storageId, plus voliteľné access (restricted predvolené | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (iba URL odkazy) a folder (+ folderDomain) na vytvorenie v priečinku. Skrátený zápis vytvorí jeden variant s názvom main; password, starts, expires a maxOpenings na najvyššej úrovni tvoria bránu odkazu. Odpoveď: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.
GET /links vracia jednu stránku, { "items": [...], "cursor" }: ?limit= je 1-100 (predvolene 50); odovzdávajte ?cursor= z predchádzajúcej stránky, kým nie je null. q hľadá celé slová (posledné ako prefix), výsledky sú zoradené podľa relevancie. Položky sú { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (riadky priečinkov pridávajú items); filter kind pridáva folder a group, filter status pridáva mixed a folder=<slug>|root (+ folderDomain) vypíše jeden priečinok alebo najvyššiu úroveň. GET /links/:id vracia celý odkaz s access a variants; obsah (destinationUrl / textContent / fileName) je uložený pri každom variante.
Nahratie súboru
Vygenerujte URL na nahratie ({uploadUrl,storageId}), odošlite bajty cez PUT z hostiteľa a potom v rovnakom postupe vytvorte 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é súbory môžu stále použiť multipart na POST /links:
curl https://api.linkdash.dev/v1/links \
-H "Authorization: Bearer ldash_..." \
-F "file=@./deck.pdf" \
-F "expires=7d" \
-F "slug=deck"
Voliteľné multipart polia: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.
Aktualizácia, štatistiky, CSV
PATCH /links/:id prijíma JSON alebo multipart. Bajty súboru nahradíte pomocou storageId po POST /uploads + PUT hostiteľa, alebo multipart poľom file (iba odkazy s jedným variantom). --status / { "status": "expired" } sa zamietne – použite expires. { "status": "scheduled" } sa zamietne – použite starts. Voliteľné maxOpenings pozastaví odkaz po danom počte otvorení; clearMaxOpenings limit odstráni. sticky (boolean) a restartSplit (boolean) riadia priraďovanie variantov; forwardParams (boolean) preposiela query string návštevníka, pozri Preposielanie query parametrov. access určuje, kto môže odkaz otvoriť; resetShareLink: true vydá novú URL na zdieľanie. Odpoveď: { "id", "url", "access", "status", "variantStatuses" }.
GET /links/:id/stats?last=24h vracia visits, downloads, plays, visitsInLast, countries, referrers, variants (súčty za jednotlivé varianty), visitors a crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: boty a náhľady odkazov, ktoré odkaz načítali, nikdy sa nezapočítavajú ako návštevy; pozri Záznam crawlerov).
GET /links/export je CSV so stĺpcami slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, jeden riadok na variant (folder je slug nadradeného priečinka; access je restricted, link alebo public). POST /links/import prijíma surové CSV alebo multipart file; riadky sa zoskupujú podľa slugu + domény (prvý riadok vytvorí odkaz s jeho variantom, ďalšie riadky pridajú varianty; pri existujúcich odkazoch sa aktualizujú polia a potom sa podľa názvu aktualizujú alebo pridajú varianty). Riadky s kind folder (s name) vytvárajú priečinky a stĺpec folder umiestni odkazy až potom, ako existujú všetky riadky. Prázdne access nastaví nové odkazy ako obmedzené a existujúce odkazy ponechá bez zmeny.
DELETE /links/:id na priečinku prijíma ?contents=keep (predvolené: položky sa presunú o úroveň vyššie) alebo ?contents=delete (odstránia sa aj položky a priečinky v ňom).
Varianty
Každý odkaz je kontajner jedného alebo viacerých variantov: obsah (url | file | text) plus vlastná brána (password, paused, starts, expires, maxOpenings), weight a voliteľné podmienky pre návštevníka when. Odkazu patrí slug, doména, názov, štítky, náhľad, jeho vlastná brána (ktorá má prednosť pred bránami variantov), sticky (predvolene true) a splitVersion (zvyšuje sa pomocou restartSplit). Bez variants má odkaz jeden variant s názvom main. Názvy: malé písmená, číslice, vnútorné spojovníky, 1–40 znakov, jedinečné v rámci odkazu. Najviac 20 variantov na odkaz.
Návštevník dostane jeden variant: varianty, ktorých when vyhovuje, tvoria výberovú množinu (ak nevyhovuje žiadny, použijú sa nepodmienené varianty), potom nasleduje vážený výber (sticky hash návštevníka + odkazu + splitVersion, inak náhodne). Crawlery dostanú prvý aktívny nepodmienený variant. kind odkazu je group, ak má viac variantov. status odkazu je stav brány odkazu, ak je nastavená, inak stav spoločný pre všetky varianty, inak mixed. variantStatuses počíta { active, paused, expired, scheduled }.
Vytvorenie viacerých variantov naraz:
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ý variant: name (povinné), jedno z url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. Vytvorenie cez multipart podporuje iba skrátený zápis.
| Trasa | Telo | Odpoveď |
|---|---|---|
GET /links/:id/variants |
— | pole variantov |
POST /links/:id/variants |
JSON alebo multipart file: name (povinné), obsah, password, starts, expires, maxOpenings, utm, weight, when |
variant |
PATCH /links/:id/variants/:name |
name (premenovanie), url, text, storageId / file, password, clearPassword, starts, clearStarts, expires, clearExpires, maxOpenings, clearMaxOpenings, status (active | paused), weight, when, clearWhen, utm |
variant |
DELETE /links/:id/variants/:name |
— | { "id", "variant", "deleted": true } (posledný variant nemožno odstrániť) |
Kľúče when (polia reťazcov; každý nastavený kľúč musí vyhovovať): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (prefix), referrerHosts (prípona hostiteľa).
Pravidlá query parametrov
when.params je pole s najviac 10 pravidlami pre query string návštevníka (lida.sh/promo?src=newsletter); musia platiť všetky pravidlá. Každé pravidlo má tvar { "key", "op", "value" }, kde op je jedno z equals | notEquals | includes | startsWith | endsWith | in (value je zoznam oddelený | alebo čiarkou) | exists | missing. value je povinné okrem exists / missing. Kľúče rozlišujú veľké a malé písmená, hodnoty sa porovnávajú presne.
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
Hodnoty parametrov sa vyhodnocujú pri otvorení a nikdy sa neukladajú do analytiky.
Preposielanie query parametrov
forwardParams (boolean na odkaze, predvolene false; dá sa nastaviť v POST /links a PATCH /links/:id, vracia ho GET /links/:id) pripojí celý query string návštevníka k URL variantom. Hodnoty od návštevníka prepíšu uložené hodnoty vrátane utm. Súborové a textové varianty ho ignorujú. Ide o smerovanie, nie o riadenie prístupu: parametre môže pridať ktokoľvek. Hodnoty parametrov sa neukladajú do analytiky.
Priečinky
Priečinok je odkaz, ktorý zobrazuje zoznam položiek, ktoré doň vložíte. Model je opísaný na stránke Priečinky.
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_..."
| Trasa | Telo | Odpoveď |
|---|---|---|
POST /links |
{ "kind": "folder", "name" } plus bežné polia odkazu; bez url, text, storageId alebo variants |
vytvorený priečinok |
POST /links/:id/move |
{ "folder": "<slug>" } alebo { "folder": null } pre najvyššiu úroveň, voliteľné folderDomain |
{ "id", "folder" } |
POST /links/:id/copy |
— | { "id", "url", "access", "kind", "variants", "folder", … } (rovnaký prístup, nová URL na zdieľanie, bez ľudí) |
Presun aj kópia sa každý započítavajú ako jedna udalosť. Neznámy slug priečinka vracia 404 (Folder "<slug>" not found); slug, ktorý nie je priečinkom, alebo presun priečinka do seba samého či do priečinka pod ním vracia 400. Priečinky možno vnoriť najviac do hĺbky 32.
Prístup a zdieľanie
Každý odkaz a priečinok má access: restricted (predvolené; vlastník a ľudia, s ktorými je zdieľaný, po prihlásení, na https://linkdash.dev/s/<token>), link (ktokoľvek s touto URL) alebo public (ktokoľvek, na krátkej URL). Nastavte ho v POST /links alebo PATCH /links/:id. Pre odkazy určené na verejné zverejnenie odovzdajte "access": "public". Ako fungujú priečinky a diváci, nájdete na stránke Zdieľanie a prí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_..."
| Trasa | Telo | Odpoveď |
|---|---|---|
POST /links/:id/shares |
{ "emails": [...] } (1–50 e-mailov) |
{ "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šetko, čo ste zdieľali) |
GET /shared |
— | { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" } |
DELETE /shared/:id |
— | { "_id", "left": true } (:id je _id alebo token zdieľania z GET /shared) |
POST /links/:id/reset-link |
— | { "id", "access", "url" } |
POST /links/:id/shares prijíma "role": "editor" pre editorov. Editori môžu meniť položky a vidia štatistiky a aktivitu, ale nikdy nemôžu meniť heslá, slug, doménu, prístup ani zdieľanie a nemôžu odstraňovať, presúvať ani kopírovať (403). Ako :id používajú _id položky alebo token zdieľania a variant chránený heslom zostáva locked: true, kým nezavolajú POST /links/:id/unlock (30 minút, desať nesprávnych hesiel za hodinu, potom 429). Uloženie po tom, čo medzitým uložil niekto iný, vráti 409 iba vtedy, keď požiadavka posiela expectedVersion. Všetky trasy zdieľania prijímajú ?domain=, keď sa slug opakuje. accepted je false, kým daný e-mail nemá overený účet; viaFolder znamená, že prístup pochádza z nadradeného priečinka. Najviac 200 ľudí na položku a 100 e-mailov s pozvánkou na účet za deň. GET /shares a GET /shared vracajú výsledky po stránkach: ?limit= je 1-100 (predvolene 50); odovzdávajte ?cursor= z predchádzajúcej stránky, kým cursor nie je null. Zdieľanie, zrušenie zdieľania a reset sa každé započítavajú ako jedna udalosť; opustenie nie. Prístup cez zdieľaný nadradený priečinok zostáva zachovaný aj po opustení.
Chyby
| Stav | Kedy |
|---|---|
| 400 | Validácia, chýbajúce telo, kombinované typy vytvorenia |
| 401 | Chýbajúci alebo neplatný bearer kľúč |
| 404 | Neznámy slug, doména alebo priečinok |
| 409 | Slug je obsadený (code: "slug_taken") |
| 429 | Dosiahnutá mesačná kvóta udalostí |
| 503 | API kľúče nie sú v tomto nasadení nakonfigurované |
Tieto endpointy opisujú stránky webhooky a vlastné domény.

