Přejít k obsahu
LinkdashLinkdash
Čeština
Esc
↑↓navigace↵otevřít⌘Jnáhled
Na této stránce

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, text nebo storageId (po POST /uploads), nebo pole variants (viz Varianty), nebo "kind": "folder" s name (viz Složky). Vygenerování vrací { "uploadUrl", "storageId" }. Hostitel nahraje bajty metodou PUT na uploadUrl. Malé soubory mohou stále použít multipart pole file v POST /links.
  • Doby trvání: 7d, 24h, 30m, 1w nebo 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šte maxOpenings nebo použijte clearMaxOpenings. Pro neomezený počet maxOpenings vynechte.
  • Pokud slug existuje na dvou doménách vlastníka, předejte ?domain= / JSON domain.
  • Chyby: { "error": "..." } a volitelně code. Obsazené slugy lida.sh vracejí 409 s code: "slug_taken".
  • Přístup: nové odkazy a složky jsou restricted, pokud tělo nenastaví access (viz Přístup a sdílení). url v 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.

Byla tato stránka užitečná?