Prejsť na obsah
LinkdashLinkdash
Slovenčina
Esc
↑↓navigácia↵otvoriť⌘Jnáhľad
Na tejto stránke

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, text alebo storageId po POST /uploads, alebo pole variants (pozri Varianty), alebo "kind": "folder" s name (pozri Priečinky). Vygenerovanie URL na nahratie vracia { "uploadUrl", "storageId" }. Hostiteľ odošle bajty cez PUT na uploadUrl. Malé súbory môžu stále použiť multipart file na POST /links.
  • Trvania: 7d, 24h, 30m, 1w alebo 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ýšte maxOpenings alebo použite clearMaxOpenings. Pre neobmedzený počet maxOpenings vynechajte.
  • Ak slug existuje na dvoch doménach vlastníka, odovzdajte ?domain= / JSON domain.
  • Chyby: { "error": "..." } plus voliteľný code. Obsadené slugy lida.sh vracajú 409 s code: "slug_taken".
  • Prístup: nové odkazy a priečinky sú restricted, pokiaľ telo nenastaví access (pozri Prístup a zdieľanie). url v 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.

Bola táto stránka užitočná?