HTTP API
REST a https://api.linkdash.dev/v1 címen, a dashboardon létrehozott bearer kulccsal. Ugyanazok a műveletek, mint a CLI-ban és az MCP-ben.
Alap URL: https://api.linkdash.dev/v1
Hitelesítés: Authorization: Bearer ldash_... (kulcsot a Dashboard → API-kulcsok oldalon hozhatsz létre). Ne találj ki kulcsokat.
CLI-referencia: CLI. MCP: MCP. Árazás / kvóták: Árazás. Felderítés (hitelesítés nélkül): GET https://api.linkdash.dev/v1. Sima markdown: api.md.
A nyilvános azonosítók slugok (deck, k3m9xq), nem a Convex _id. A JSON-mezők nevei megegyeznek a CLI stdout kimenetében szereplőkkel (id, url, kind, …).
Konvenciók
- JSON,
Content-Type: application/json, hacsak másként nincs jelölve. - A létrehozás pontosan egyet vár a következők közül:
url,text, vagyPOST /uploadsutánstorageId, vagy egyvariantstömböt (lásd Változatok), vagy"kind": "folder"értéket egynamemezővel (lásd Mappák). A feltöltési URL generálása{ "uploadUrl", "storageId" }értéket ad vissza. A host PUT kéréssel küldi fel a bájtokat azuploadUrlcímre. Kis fájlokhoz továbbra is használhatod a multipartfilemezőt aPOST /linksvégponton. - Időtartamok:
7d,24h,30m,1wvagy ISO-dátum. Mezők:expires/expiresAt,starts/startsAt. - Megnyitási korlát: opcionális, pozitív egész
maxOpenings. A link ennyi sikeres megnyitás után szünetel. Ha újra ki akarod szolgálni, növeld amaxOpeningsértékét, vagy használd aclearMaxOpeningsmezőt. Korlátlan megnyitáshoz hagyd el amaxOpeningsmezőt. - Ha egy slug a tulajdonos két domainjén is létezik, add meg a
?domain=paramétert / a JSONdomainmezőt. - Hibák:
{ "error": "..." }, opcionálisancodemezővel. Foglaltlida.shslug esetén a válasz409,code: "slug_taken"értékkel. - Hozzáférés: az új linkek és mappák
restrictedhozzáférésűek, hacsak a body nem állítja be azaccessmezőt (lásd Hozzáférés és megosztás). A válaszokban azurla megosztási URL (https://linkdash.dev/s/<token>), kivéve, ha a link nyilvános – ilyenkor a rövid URL. - Az írások beleszámítanak a havi eseménykvótába (a share, az unshare és a reset is). A list / get / stats / export / shares list / shared / webhook list/get nem számít bele. A visit / download / play események rögzítése továbbra is beleszámít.
Végpontok
| 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 nélkül) |
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 nélkül) |
|
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 |
| (host PUT a generálás utá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_* |
Az auth create, az auth login és az auth logout böngészős device flow-k. Ezek nem Unkey-útvonalak.
GET /me
A bejelentkezett fiók. { "userId": "...", "email": "...", "name": "..." }. Az e-mail és a név kimarad, ha nem ismert.
URL-link létrehozása
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"}'
A JSON body pontosan egyet vár a következők közül: url, text vagy storageId, emellett opcionálisan: access (restricted az alapértelmezés | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (csak URL-linkeknél), valamint folder (+ folderDomain), ha mappán belül akarod létrehozni. A rövidített forma egyetlen, main nevű változatot hoz létre; a legfelső szintű password, starts, expires és maxOpenings a link kapuja. Válasz: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.
A GET /links egy oldalt ad vissza, { "items": [...], "cursor" } formában: a ?limit= értéke 1-100 (alapértelmezés: 50); add át az előző oldalból kapott ?cursor= értéket, amíg az null nem lesz. A q egész szavakra illeszkedik (az utolsó szóra prefixként), relevancia szerint rangsorolva. Az elemek alakja { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (a mappasorok items mezőt is kapnak); a kind szűrő a folder és a group értékkel bővül, a status szűrő a mixed értékkel, a folder=<slug>|root (+ folderDomain) pedig egy mappát vagy a legfelső szintet listázza. A GET /links/:id a teljes linket adja vissza access és variants mezőkkel; a tartalom (destinationUrl / textContent / fileName) az egyes változatokon található.
Fájl feltöltése
Generálj egy feltöltési URL-t ({uploadUrl,storageId}), töltsd fel a bájtokat PUT-tal a hostról, majd ugyanabban a folyamatban hozd létre a linket:
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}'
Kis fájlokhoz továbbra is használhatod a multipartot a POST /links végponton:
curl https://api.linkdash.dev/v1/links \
-H "Authorization: Bearer ldash_..." \
-F "file=@./deck.pdf" \
-F "expires=7d" \
-F "slug=deck"
Opcionális multipart mezők: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.
Frissítés, statisztika, CSV
A PATCH /links/:id JSON-t vagy multipartot fogad. A fájl bájtjait lecserélheted storageId-vel (POST /uploads + host PUT után), vagy a file multipart mezővel (csak egyváltozatos linkeknél). A --status / { "status": "expired" } elutasításra kerül – használd az expires mezőt. A { "status": "scheduled" } is elutasításra kerül – használd a starts mezőt. Az opcionális maxOpenings ennyi megnyitás után szünetelteti a linket; a clearMaxOpenings eltávolítja a korlátot. A sticky (boolean) és a restartSplit (boolean) a változatok kiosztását vezérli; a forwardParams (boolean) továbbítja a látogató query stringjét, lásd Query paraméterek továbbítása. Az access azt szabályozza, ki nyithatja meg; a resetShareLink: true új megosztási URL-t ad ki. Válasz: { "id", "url", "access", "status", "variantStatuses" }.
A GET /links/:id/stats?last=24h a következőket adja vissza: visits, downloads, plays, visitsInLast, countries, referrers, variants (változatonkénti összesítések), visitors és crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: botok és linkelőnézetek, amelyek lekérték a linket – ezek sosem számítanak látogatásnak; lásd Crawler-napló).
A GET /links/export CSV-t ad vissza a következő oszlopokkal: slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, változatonként egy sorral (a folder a tartalmazó mappa slugja; az access értéke restricted, link vagy public). A POST /links/import nyers CSV-t vagy multipart file mezőt fogad; a sorok slug + domain szerint csoportosulnak (az első sor létrehozza a linket a változatával, a további sorok változatokat adnak hozzá; meglévő linkeknél előbb a mezők frissülnek, majd név szerint frissülnek vagy hozzáadódnak a változatok). A folder kind értékű sorok (name mezővel) mappákat hoznak létre, a folder oszlop pedig csak azután helyezi el a linkeket, hogy minden sor létrejött. Üres access esetén az új linkek korlátozottak lesznek, a meglévők pedig változatlanok maradnak.
A DELETE /links/:id mappa esetén a ?contents=keep (alapértelmezés: az elemek egy szinttel feljebb kerülnek) vagy a ?contents=delete (a benne lévő elemek és mappák is törlődnek) paramétert fogadja.
Változatok
Minden link egy vagy több változat tárolója. Egy változat tartalomból (url | file | text), saját kapuból (password, paused, starts, expires, maxOpenings), egy weight értékből és opcionális látogatói feltételekből (when) áll. A linkhez tartozik a slug, a domain, a név, a címkék, az előnézet, a saját kapuja (amely felülírja a változatok kapuit), a sticky (alapértelmezés: true) és a splitVersion (ezt a restartSplit növeli). variants nélkül a linknek egyetlen, main nevű változata van. Nevek: kisbetűk, számjegyek, belső kötőjelek, 1–40 karakter, linkenként egyediek. Linkenként legfeljebb 20 változat lehet.
A látogató egy változatot kap: a készletet azok a változatok alkotják, amelyek when feltétele illeszkedik (ha egyik sem illeszkedik, akkor a feltétel nélküliek), ebből súlyozott választás történik (a látogató + link + splitVersion sticky hash-e alapján, egyébként véletlenszerűen). A crawlerek az első élő, feltétel nélküli változatot kapják. Több változat esetén a link kind értéke group. A link status értéke a link kapuja, ha az be van állítva; ha nincs, akkor az a státusz, amely minden változatnál azonos; egyébként mixed. A variantStatuses a { active, paused, expired, scheduled } darabszámokat tartalmazza.
Több változat létrehozása egyszerre:
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"]}}]}'
Minden változat mezői: name (kötelező), egy a következők közül: url | text | storageId (+ fileName, fileType, fileSize), továbbá password, starts, expires, maxOpenings, utm, weight, when. A multipart létrehozás továbbra is csak a rövidített formát támogatja.
| Útvonal | Body | Válasz |
|---|---|---|
GET /links/:id/variants |
— | a változatok tömbje |
POST /links/:id/variants |
JSON vagy multipart file: name (kötelező), tartalom, password, starts, expires, maxOpenings, utm, weight, when |
a változat |
PATCH /links/:id/variants/:name |
name (átnevezés), url, text, storageId / file, password, clearPassword, starts, clearStarts, expires, clearExpires, maxOpenings, clearMaxOpenings, status (active | paused), weight, when, clearWhen, utm |
a változat |
DELETE /links/:id/variants/:name |
— | { "id", "variant", "deleted": true } (az utolsó változat nem törölhető) |
A when kulcsai (stringtömbök; minden beállított kulcsnak illeszkednie kell): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (prefix), referrerHosts (host-utótag).
Query paraméter szabályok
A when.params legfeljebb 10 szabályból álló tömb, amely a látogató query stringjére vonatkozik (lida.sh/promo?src=newsletter); minden szabálynak teljesülnie kell. Minden szabály { "key", "op", "value" } alakú, ahol az op a következők egyike: equals | notEquals | includes | startsWith | endsWith | in (a value |-vel vagy vesszővel elválasztott lista) | exists | missing. A value kötelező, kivéve exists / missing esetén. A kulcsok kis- és nagybetűérzékenyek, az értékeket pontos egyezésre vizsgálja.
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
A paraméterértékek illesztése megnyitáskor történik, és ezek sosem kerülnek tárolásra az analitikában.
Query paraméterek továbbítása
A forwardParams (boolean a linken, alapértelmezés: false; beállítható a POST /links és a PATCH /links/:id végponton, a GET /links/:id visszaadja) a látogató teljes query stringjét hozzáfűzi az URL-változatokhoz. A látogató által küldött értékek felülírják a tároltakat, az utm-et is beleértve. A fájl- és szövegváltozatok figyelmen kívül hagyják. Ez útválasztás, nem hozzáférés-szabályozás: bárki hozzáadhat paramétereket. A paraméterértékek nem kerülnek tárolásra az analitikában.
Mappák
A mappa egy olyan link, amely felsorolja a beletett elemeket. A modellről a Mappák oldalon olvashatsz.
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_..."
| Útvonal | Body | Válasz |
|---|---|---|
POST /links |
{ "kind": "folder", "name" } plusz a szokásos linkmezők; url, text, storageId és variants nélkül |
a létrehozott mappa |
POST /links/:id/move |
{ "folder": "<slug>" }, vagy a legfelső szinthez { "folder": null }, opcionálisan folderDomain |
{ "id", "folder" } |
POST /links/:id/copy |
— | { "id", "url", "access", "kind", "variants", "folder", … } (azonos hozzáférés, új megosztási URL, megosztott személyek nélkül) |
Az áthelyezés és a másolás egyaránt egy eseménynek számít. Ismeretlen mappaslug esetén a válasz 404 (Folder "<slug>" not found); ha a slug nem mappa, vagy egy mappát önmagába vagy egy alatta lévő mappába helyeznél át, a válasz 400. A mappák legfeljebb 32 szint mélyen ágyazhatók egymásba.
Hozzáférés és megosztás
Minden linknek és mappának van access értéke: restricted (alapértelmezés; a tulajdonos és azok, akikkel megosztották, bejelentkezve, a https://linkdash.dev/s/<token> címen), link (bárki, akinél megvan az URL) vagy public (bárki, a rövid URL-en). A POST /links vagy a PATCH /links/:id végponton állíthatod be. Nyilvános közzétételre szánt linkekhez add meg az "access": "public" értéket. A mappák és a megtekintők működéséről a Megosztás és hozzáférés oldalon olvashatsz.
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_..."
| Útvonal | Body | Válasz |
|---|---|---|
POST /links/:id/shares |
{ "emails": [...] } (1–50 e-mail-cím) |
{ "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" } (minden, amit megosztottál) |
GET /shared |
— | { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" } |
DELETE /shared/:id |
— | { "_id", "left": true } (az :id a GET /shared által visszaadott _id vagy megosztási token) |
POST /links/:id/reset-link |
— | { "id", "access", "url" } |
Szerkesztők meghívásához a POST /links/:id/shares a "role": "editor" értéket fogadja. A szerkesztők módosíthatják az elemeket, és látják a statisztikákat és az aktivitást, de a jelszavakhoz, a slughoz, a domainhez, a hozzáféréshez és a megosztáshoz sosem nyúlhatnak, és nem törölhetnek, helyezhetnek át vagy másolhatnak (403). :id-ként az elem _id értékét vagy megosztási tokenjét használják, a jelszóval védett változat pedig locked: true marad, amíg nem hívják meg a POST /links/:id/unlock végpontot (30 percre; óránként tíz hibás jelszó után 429). Ha valaki más közben már mentett, a mentés csak akkor ad 409-et, ha a kérés expectedVersion értéket küld. Minden megosztási útvonal elfogadja a ?domain= paramétert, ha a slug több domainen is szerepel. Az accepted értéke false, amíg az adott e-mail-címhez nincs ellenőrzött fiók; a viaFolder azt jelenti, hogy a hozzáférés egy feljebb lévő mappából öröklődik. Elemenként legfeljebb 200 személy lehet, és fiókonként naponta legfeljebb 100 meghívó e-mail mehet ki. A GET /shares és a GET /shared egyszerre egy oldalt ad vissza: a ?limit= értéke 1-100 (alapértelmezés: 50); add át az előző oldalból kapott ?cursor= értéket, amíg a cursor null nem lesz. A megosztás, a megosztás visszavonása és a reset egyenként egy eseménynek számít; a kilépés nem. Ha egy feljebb lévő megosztott mappán keresztül is van hozzáférésed, az kilépés után is megmarad.
Hibák
| Státusz | Mikor |
|---|---|
| 400 | Validációs hiba, hiányzó body, vegyes létrehozási típusok |
| 401 | Hiányzó vagy érvénytelen bearer kulcs |
| 404 | Ismeretlen slug, domain vagy mappa |
| 409 | Foglalt slug (code: "slug_taken") |
| 429 | Elérted a havi eseménykvótát |
| 503 | Ezen a telepítésen nincsenek konfigurálva API-kulcsok |
Ezekről a végpontokról a webhookok és az egyéni domainek oldalon olvashatsz.

