Ugrás a tartalomra
LinkdashLinkdash
Magyar
Esc
↑↓navigálás↵megnyitás⌘Jelőnézet
Ezen az oldalon

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, vagy POST /uploads után storageId, vagy egy variants tömböt (lásd Változatok), vagy "kind": "folder" értéket egy name mező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 az uploadUrl címre. Kis fájlokhoz továbbra is használhatod a multipart file mezőt a POST /links végponton.
  • Időtartamok: 7d, 24h, 30m, 1w vagy 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 a maxOpenings értékét, vagy használd a clearMaxOpenings mezőt. Korlátlan megnyitáshoz hagyd el a maxOpenings mezőt.
  • Ha egy slug a tulajdonos két domainjén is létezik, add meg a ?domain= paramétert / a JSON domain mezőt.
  • Hibák: { "error": "..." }, opcionálisan code mezővel. Foglalt lida.sh slug esetén a válasz 409, code: "slug_taken" értékkel.
  • Hozzáférés: az új linkek és mappák restricted hozzáférésűek, hacsak a body nem állítja be az access mezőt (lásd Hozzáférés és megosztás). A válaszokban az url a 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.

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.

Hasznos volt ez az oldal?