HTTP API
REST na https://api.linkdash.dev/v1 s ključem bearer z nadzorne plošče. Enake operacije kot CLI in MCP.
Osnovni URL: https://api.linkdash.dev/v1
Preverjanje pristnosti: Authorization: Bearer ldash_... (ključe ustvarite na Nadzorna plošča → Ključi API). Ključev si ne izmišljujte.
Referenca CLI: CLI. MCP: MCP. Cene / kvote: Cene. Odkrivanje (brez preverjanja pristnosti): GET https://api.linkdash.dev/v1. Navaden markdown: api.md.
Javni ID-ji so slugi (deck, k3m9xq), ne Convex _id. Imena polj JSON se ujemajo z izhodom CLI na stdout (id, url, kind, …).
Dogovori
- JSON
Content-Type: application/json, razen če ni navedeno drugače. - Ustvarjanje sprejme natanko eno od
url,textalistorageIdpoPOST /uploads, ali poljevariants(glejte Različice), ali"kind": "folder"zname(glejte Mape). Ustvarjanje URL-ja za nalaganje vrne{ "uploadUrl", "storageId" }. Gostitelj z ukazom PUT pošlje bajte nauploadUrl. Majhne datoteke lahko še vedno uporabijo multipartfilenaPOST /links. - Trajanja:
7d,24h,30m,1wali datum ISO. Polja:expires/expiresAt,starts/startsAt. - Omejitev odpiranj: izbirno pozitivno celo število
maxOpenings. Povezava se po toliko uspešnih odpiranjih zaustavi. PovečajtemaxOpeningsali uporabiteclearMaxOpenings, da jo znova strežete. Za neomejeno število odpiranj izpustitemaxOpenings. - Če slug obstaja na dveh lastnikovih domenah, podajte
?domain=/ JSONdomain. - Napake:
{ "error": "..." }in izbirnocode. Zasedeni slugilida.shvrnejo409scode: "slug_taken". - Dostop: nove povezave in mape so
restricted, razen če telo nastaviaccess(glejte Dostop in deljenje).urlv odgovorih je URL za deljenje (https://linkdash.dev/s/<token>), razen če je povezava javna; takrat je to kratki URL. - Pisanja se štejejo v mesečno kvoto dogodkov (vključno z deljenjem, preklicem deljenja in ponastavitvijo). List / get / stats / export / seznam deljenj / shared / webhook list/get se ne štejejo. Zajem obiskov / prenosov / predvajanj se še vedno šteje.
Končne točke
| 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 (brez 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 (brez 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 gostitelja po ustvarjanju URL-ja) | 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 in auth logout so tokovi naprave v brskalniku. Niso poti Unkey.
GET /me
Prijavljeni račun. { "userId": "...", "email": "...", "name": "..." }. E-pošta in ime sta izpuščena, kadar nista znana.
Ustvarjanje povezave 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"}'
Telo JSON sprejme natanko eno od url, text ali storageId, poleg tega pa izbirno še access (restricted privzeto | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (samo povezave URL) in folder (+ folderDomain) za ustvarjanje znotraj mape. Skrajšana oblika ustvari eno različico z imenom main; password, starts, expires in maxOpenings na najvišji ravni so zapora povezave. Odgovor: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.
GET /links vrne eno stran, { "items": [...], "cursor" }: ?limit= je 1-100 (privzeto 50); podajajte ?cursor= iz prejšnje strani, dokler ni null. q se ujema s celimi besedami (zadnja kot predpona), rezultati so razvrščeni po ustreznosti. Elementi so { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (vrstice map dodajo items); filter kind doda folder in group, filter status doda mixed, folder=<slug>|root (+ folderDomain) pa izpiše eno mapo ali najvišjo raven. GET /links/:id vrne celotno povezavo z access in variants; vsebina (destinationUrl / textContent / fileName) je shranjena na posamezni različici.
Nalaganje datoteke
Ustvarite URL za nalaganje ({uploadUrl,storageId}), z gostitelja pošljite bajte z ukazom PUT, nato v istem toku ustvarite povezavo:
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}'
Majhne datoteke lahko še vedno uporabijo 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"
Izbirna polja multipart: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.
Posodobitev, statistika, CSV
PATCH /links/:id je JSON ali multipart. Bajte datoteke zamenjajte s storageId po POST /uploads + PUT gostitelja ali s poljem multipart file (samo povezave z eno različico). --status / { "status": "expired" } je zavrnjen — uporabite expires. { "status": "scheduled" } je zavrnjen — uporabite starts. Izbirni maxOpenings zaustavi povezavo po toliko odpiranjih; clearMaxOpenings odstrani omejitev. sticky (boolean) in restartSplit (boolean) nadzorujeta dodeljevanje različic; forwardParams (boolean) posreduje poizvedbeni niz obiskovalca, glejte Posredovanje parametrov poizvedbe. access spremeni, kdo jo lahko odpre; resetShareLink: true izda nov URL za deljenje. Odgovor: { "id", "url", "access", "status", "variantStatuses" }.
GET /links/:id/stats?last=24h vrne visits, downloads, plays, visitsInLast, countries, referrers, variants (skupne vrednosti po različicah), visitors in crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: boti in predogledi povezav, ki so pridobili povezavo in se nikoli ne štejejo kot obiski; glejte Dnevnik pajkov).
GET /links/export je CSV s stolpci slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, z eno vrstico na različico (folder je slug mape, ki vsebuje povezavo; access je restricted, link ali public). POST /links/import sprejme surov CSV ali multipart file; vrstice so združene po slugu + domeni (prva vrstica ustvari povezavo z njeno različico, nadaljnje vrstice dodajo različice; pri obstoječih povezavah se posodobijo polja, nato pa se različice posodobijo ali dodajo po imenu). Vrstice s kind folder (z name) ustvarijo mape, stolpec folder pa povezave razporedi, ko obstajajo vse vrstice. Prazen access naredi nove povezave omejene, obstoječe pa pusti nespremenjene.
DELETE /links/:id na mapi sprejme ?contents=keep (privzeto: elementi se premaknejo za raven višje) ali ?contents=delete (izbrišejo se tudi elementi in mape v njej).
Različice
Vsaka povezava je vsebnik ene ali več različic: vsebine (url | file | text) z lastno zaporo (password, paused, starts, expires, maxOpenings), utežjo weight in izbirnimi pogoji za obiskovalce when. Povezavi pripadajo slug, domena, ime, oznake, predogled, lastna zapora (ki ima prednost pred zaporami različic), sticky (privzeto true) in splitVersion (poveča ga restartSplit). Brez variants ima povezava eno različico z imenom main. Imena: male črke, števke, notranji vezaji, 1–40 znakov, edinstvena znotraj povezave. Največ 20 različic na povezavo.
Obiskovalec dobi eno različico: različice, katerih when se ujema, tvorijo nabor (če se nobena ne ujema, ga tvorijo brezpogojne različice), nato sledi utežena izbira (lepljiva zgoščena vrednost obiskovalca + povezave + splitVersion, sicer naključno). Pajki dobijo prvo aktivno brezpogojno različico. kind povezave je group, kadar ima več različic. status povezave je zapora povezave, kadar je nastavljena, sicer status, ki ga imajo vse različice, sicer mixed. variantStatuses šteje { active, paused, expired, scheduled }.
Ustvarite več različic hkrati:
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"]}}]}'
Vsaka različica: name (obvezno), eno od url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. Ustvarjanje z multipart ostaja samo v skrajšani obliki.
| Pot | Telo | Odgovor |
|---|---|---|
GET /links/:id/variants |
— | polje različic |
POST /links/:id/variants |
JSON ali multipart file: name (obvezno), vsebina, password, starts, expires, maxOpenings, utm, weight, when |
različica |
PATCH /links/:id/variants/:name |
name (preimenovanje), url, text, storageId / file, password, clearPassword, starts, clearStarts, expires, clearExpires, maxOpenings, clearMaxOpenings, status (active | paused), weight, when, clearWhen, utm |
različica |
DELETE /links/:id/variants/:name |
— | { "id", "variant", "deleted": true } (zadnje različice ni mogoče izbrisati) |
Ključi when (polja nizov; ujemati se mora vsak nastavljen ključ): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (predpona), referrerHosts (pripona gostitelja).
Pravila parametrov poizvedbe
when.params je polje do 10 pravil za poizvedbeni niz obiskovalca (lida.sh/promo?src=newsletter); veljati mora vsako pravilo. Vsako pravilo je { "key", "op", "value" }, pri čemer je op eno od equals | notEquals | includes | startsWith | endsWith | in (value je seznam, ločen z | ali vejico) | exists | missing. value je obvezen, razen pri exists / missing. Ključi razlikujejo med velikimi in malimi črkami, vrednosti se primerjajo natančno.
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
Vrednosti parametrov se preverjajo ob odpiranju in se nikoli ne shranijo v analitiko.
Posredovanje parametrov poizvedbe
forwardParams (boolean na povezavi, privzeto false; nastavljiv na POST /links in PATCH /links/:id, vrne ga GET /links/:id) različicam URL doda celoten poizvedbeni niz obiskovalca. Vrednosti obiskovalca preglasijo shranjene, vključno z utm. Različice z datoteko in besedilom ga prezrejo. To je usmerjanje, ne nadzor dostopa: parametre lahko doda kdorkoli. Vrednosti parametrov se ne shranjujejo v analitiko.
Mape
Mapa je povezava, ki navaja elemente, ki jih vstavite vanjo. Za opis modela glejte Mape.
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_..."
| Pot | Telo | Odgovor |
|---|---|---|
POST /links |
{ "kind": "folder", "name" } in običajna polja povezave; brez url, text, storageId ali variants |
ustvarjena mapa |
POST /links/:id/move |
{ "folder": "<slug>" } ali { "folder": null } za najvišjo raven, izbirno folderDomain |
{ "id", "folder" } |
POST /links/:id/copy |
— | { "id", "url", "access", "kind", "variants", "folder", … } (enak dostop, nov URL za deljenje, brez oseb) |
Premik in kopiranje se štejeta vsak kot en dogodek. Neznan slug mape vrne 404 (Folder "<slug>" not found); slug, ki ni mapa, ali premik mape vase ali v mapo pod njo vrne 400. Mape je mogoče gnezditi največ 32 ravni globoko.
Dostop in deljenje
Vsaka povezava in mapa ima access: restricted (privzeto; lastnik in osebe, s katerimi je deljena, ko so prijavljeni, na https://linkdash.dev/s/<token>), link (kdorkoli s tem URL-jem) ali public (kdorkoli, na kratkem URL-ju). Nastavite ga na POST /links ali PATCH /links/:id. Za povezave, namenjene javni objavi, podajte "access": "public". Kako delujejo mape in gledalci, si oglejte v Deljenje in dostop.
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_..."
| Pot | Telo | Odgovor |
|---|---|---|
POST /links/:id/shares |
{ "emails": [...] } (1–50 e-poštnih naslovov) |
{ "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" } (vse, kar ste delili) |
GET /shared |
— | { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" } |
DELETE /shared/:id |
— | { "_id", "left": true } (:id je _id ali žeton za deljenje iz GET /shared) |
POST /links/:id/reset-link |
— | { "id", "access", "url" } |
POST /links/:id/shares za urednike sprejme "role": "editor". Uredniki spreminjajo elemente ter vidijo statistiko in dejavnost, nikoli pa ne vidijo gesel in ne morejo spreminjati sluga, domene, dostopa in deljenja ter ne morejo brisati, premikati ali kopirati (403); kot :id uporabljajo _id elementa ali žeton za deljenje, različica, zaščitena z geslom, pa ostane locked: true, dokler ne pokličejo POST /links/:id/unlock (30 minut, deset napačnih gesel na uro, nato 429). Shranjevanje, potem ko je shranil že nekdo drug, vrne 409 le, če zahteva pošlje expectedVersion. Vse poti za deljenje sprejmejo ?domain=, kadar se slug ponavlja. accepted je false, dokler ta e-poštni naslov nima preverjenega računa; viaFolder pomeni, da dostop izhaja iz mape višje. Do 200 oseb na element in 100 e-poštnih povabil na račun na dan. GET /shares in GET /shared vračata eno stran naenkrat: ?limit= je 1-100 (privzeto 50); podajajte ?cursor= iz prejšnje strani, dokler cursor ni null. Deljenje, preklic deljenja in ponastavitev se štejejo vsak kot en dogodek; zapustitev se ne šteje. Dostop prek deljene mape višje ostane tudi po zapustitvi.
Napake
| Stanje | Kdaj |
|---|---|
| 400 | Preverjanje veljavnosti, manjkajoče telo, mešane vrste ustvarjanja |
| 401 | Manjkajoč ali neveljaven ključ bearer |
| 404 | Neznan slug, domena ali mapa |
| 409 | Slug je zaseden (code: "slug_taken") |
| 429 | Dosežena mesečna kvota dogodkov |
| 503 | Ključi API v tej namestitvi niso konfigurirani |
Za te končne točke glejte webhooke in domene po meri.

