Skip to content
LinkdashLinkdash
Lietuvių
Esc
↑↓navigate↵open⌘Jpreview
On this page

HTTP API

REST adresu https://api.linkdash.dev/v1 su prieigos raktu (bearer) iš valdymo skydelio. Tos pačios operacijos kaip CLI ir MCP.

Bazinis URL: https://api.linkdash.dev/v1

Autentifikacija: Authorization: Bearer ldash_... (raktus sukurkite skiltyje Valdymo skydelis → API raktai). Neišgalvokite raktų.

CLI žinynas: CLI. MCP: MCP. Kainos / kvotos: Kainos. Aptikimas (be autentifikacijos): GET https://api.linkdash.dev/v1. Grynasis markdown: api.md.

Vieši identifikatoriai yra slug reikšmės (deck, k3m9xq), o ne Convex _id. JSON laukų pavadinimai atitinka CLI stdout išvestį (id, url, kind, …).

Konvencijos

  • JSON Content-Type: application/json, jei nenurodyta kitaip.
  • Kūrimo užklausa priima lygiai vieną iš url, text arba storageId (po POST /uploads), arba variants masyvą (žr. Variantai), arba "kind": "folder" su name (žr. Aplankai). Išdavimas grąžina { "uploadUrl", "storageId" }. Pagrindinė sistema baitus siunčia PUT užklausa į uploadUrl. Mažiems failams vis dar galima naudoti multipart lauką file su POST /links.
  • Trukmės: 7d, 24h, 30m, 1w arba ISO data. Laukai: expires / expiresAt, starts / startsAt.
  • Atidarymų limitas: neprivalomas teigiamas sveikasis skaičius maxOpenings. Nuoroda pristabdoma po tiek sėkmingų atidarymų. Padidinkite maxOpenings arba naudokite clearMaxOpenings, kad nuoroda vėl būtų pasiekiama. Jei limito nereikia, maxOpenings nenurodykite.
  • Jei slug egzistuoja dviejuose savininko domenuose, perduokite ?domain= / JSON domain.
  • Klaidos: { "error": "..." } ir neprivalomas code. Užimti lida.sh slug grąžina 409 su code: "slug_taken".
  • Prieiga: naujos nuorodos ir aplankai yra restricted, nebent užklausos turinyje nustatytas access (žr. Prieiga ir bendrinimas). Atsakymuose url yra bendrinimo URL (https://linkdash.dev/s/<token>), nebent nuoroda yra vieša, tada tai trumpasis URL.
  • Rašymo operacijos įskaičiuojamos į mėnesio įvykių kvotą (įskaitant bendrinimą, bendrinimo atšaukimą ir atstatymą). Sąrašo / gavimo / statistikos / eksporto / bendrinimų sąrašo / su jumis bendrinamų elementų / webhook sąrašo ir gavimo operacijos neįskaičiuojamos. Apsilankymų / atsisiuntimų / paleidimų registravimas vis tiek įskaičiuojamas.

Galiniai taškai

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 (be 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 (be 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
(pagrindinės sistemos PUT po išdavimo) 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 ir auth logout yra įrenginio autorizacijos srautai naršyklėje. Tai nėra Unkey maršrutai.

GET /me

Prisijungusi paskyra. { "userId": "...", "email": "...", "name": "..." }. El. paštas ir vardas praleidžiami, kai jie nežinomi.

URL nuorodos kūrimas

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"}'

JSON užklausos turinys priima lygiai vieną iš url, text arba storageId, taip pat neprivalomus laukus access (restricted numatytasis | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (tik URL nuorodoms) ir folder (+ folderDomain), kad nuoroda būtų sukurta aplanke. Sutrumpinta forma sukuria vieną variantą pavadinimu main; aukščiausio lygio password, starts, expires ir maxOpenings yra nuorodos lygmens apribojimai. Atsakymas: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.

GET /links grąžina vieną puslapį, { "items": [...], "cursor" }: ?limit= yra 1–100 (numatytoji reikšmė 50); perduokite ?cursor= iš ankstesnio puslapio, kol jis taps null. q atitinka ištisus žodžius (paskutinį – kaip priešdėlį), rezultatai rikiuojami pagal aktualumą. Elementai yra { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (aplankų eilutės papildomai turi items); filtras kind papildomai leidžia folder ir group, filtras status papildomai leidžia mixed, o folder=<slug>|root (+ folderDomain) pateikia vieno aplanko arba aukščiausio lygio sąrašą. GET /links/:id grąžina visą nuorodą su access ir variants; turinys (destinationUrl / textContent / fileName) saugomas kiekviename variante.

Failo įkėlimas

Gaukite įkėlimo URL ({uploadUrl,storageId}), išsiųskite baitus PUT užklausa iš pagrindinės sistemos, tada tame pačiame sraute sukurkite nuorodą:

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}'

Mažiems failams vis dar galima naudoti multipart su POST /links:

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -F "file=@./deck.pdf" \
  -F "expires=7d" \
  -F "slug=deck"

Neprivalomi multipart laukai: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.

Atnaujinimas, statistika, CSV

PATCH /links/:id priima JSON arba multipart. Failo baitus pakeiskite naudodami storageId po POST /uploads ir PUT užklausos iš pagrindinės sistemos arba multipart lauką file (tik vieno varianto nuorodoms). --status / { "status": "expired" } atmetamas – naudokite expires. { "status": "scheduled" } atmetamas – naudokite starts. Neprivalomas maxOpenings pristabdo nuorodą po nurodyto atidarymų skaičiaus; clearMaxOpenings pašalina limitą. sticky (loginė reikšmė) ir restartSplit (loginė reikšmė) valdo variantų priskyrimą; forwardParams (loginė reikšmė) perduoda lankytojo užklausos eilutę, žr. Užklausos parametrų perdavimas. access keičia, kas gali ją atidaryti; resetShareLink: true išduoda naują bendrinimo URL. Atsakymas: { "id", "url", "access", "status", "variantStatuses" }.

GET /links/:id/stats?last=24h grąžina visits, downloads, plays, visitsInLast, countries, referrers, variants (kiekvieno varianto sumos), visitors ir crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: robotai ir nuorodų peržiūros, kurie užklausė nuorodą; jie niekada neskaičiuojami kaip apsilankymai; žr. Robotų žurnalas).

GET /links/export yra CSV su stulpeliais slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, po vieną eilutę kiekvienam variantui (folder yra jį turinčio aplanko slug; access yra restricted, link arba public). POST /links/import priima neapdorotą CSV arba multipart file; eilutės grupuojamos pagal slug + domeną (pirmoji eilutė sukuria nuorodą su jos variantu, kitos eilutės prideda variantus; esamų nuorodų laukai atnaujinami, tada variantai atnaujinami arba pridedami pagal pavadinimą). kind folder eilutės (su name) sukuria aplankus, o stulpelis folder paskirsto nuorodas, kai visos eilutės jau sukurtos. Tuščias access naujas nuorodas padaro ribotos prieigos, o esamas palieka nepakeistas.

DELETE /links/:id aplankui priima ?contents=keep (numatytasis: elementai perkeliami vienu lygiu aukščiau) arba ?contents=delete (taip pat ištrinami jame esantys elementai ir aplankai).

Variantai

Kiekviena nuoroda yra vieno ar daugiau variantų konteineris: turinys (url | file | text) ir savi apribojimai (password, paused, starts, expires, maxOpenings), weight bei neprivalomos lankytojo sąlygos when. Nuorodai priklauso slug, domenas, pavadinimas, žymos, peržiūra, jos pačios apribojimai (kurie turi pirmenybę prieš variantų apribojimus), sticky (numatytoji reikšmė true) ir splitVersion (padidinamas naudojant restartSplit). Be variants nuoroda turi vieną variantą pavadinimu main. Pavadinimai: mažosios raidės, skaitmenys, vidiniai brūkšneliai, 1–40 simbolių, unikalūs nuorodos ribose. Daugiausia 20 variantų vienai nuorodai.

Lankytojas gauna vieną variantą: variantai, kurių when atitinka, sudaro rinkinį (jei neatitinka nė vienas – naudojami besąlygiai variantai), tada atliekamas svertinis pasirinkimas (pastovi lankytojo + nuorodos + splitVersion maiša, kitu atveju – atsitiktinai). Robotai gauna pirmąjį aktyvų besąlygį variantą. Kai variantų keli, nuorodos kind yra group. Nuorodos status yra nuorodos apribojimų būsena, kai jie nustatyti, kitu atveju – visų variantų bendra būsena, o jei tokios nėra – mixed. variantStatuses skaičiuoja { active, paused, expired, scheduled }.

Kelių variantų kūrimas vienu metu:

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"]}}]}'

Kiekvienas variantas: name (privalomas), vienas iš url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. Multipart kūrimas palaiko tik sutrumpintą formą.

Maršrutas Užklausos turinys Atsakymas
GET /links/:id/variants — variantų masyvas
POST /links/:id/variants JSON arba multipart file: name (privalomas), turinys, password, starts, expires, maxOpenings, utm, weight, when variantas
PATCH /links/:id/variants/:name name (pervadinimas), url, text, storageId / file, password, clearPassword, starts, clearStarts, expires, clearExpires, maxOpenings, clearMaxOpenings, status (active | paused), weight, when, clearWhen, utm variantas
DELETE /links/:id/variants/:name — { "id", "variant", "deleted": true } (paskutinio varianto ištrinti negalima)

when raktai (eilučių masyvai; kiekvienas nustatytas raktas turi atitikti): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (priešdėlis), referrerHosts (pagrindinio kompiuterio pavadinimo priesaga).

Užklausos parametrų taisyklės

when.params yra iki 10 taisyklių masyvas, taikomas lankytojo užklausos eilutei (lida.sh/promo?src=newsletter); turi būti tenkinamos visos taisyklės. Kiekviena taisyklė yra { "key", "op", "value" }, kur op yra vienas iš equals | notEquals | includes | startsWith | endsWith | in (value yra | arba kableliais atskirtas sąrašas) | exists | missing. value privalomas, išskyrus exists / missing. Raktai skiria didžiąsias ir mažąsias raides, reikšmės lyginamos tiksliai.

{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }

Parametrų reikšmės tikrinamos atidarymo metu ir niekada nesaugomos analitikoje.

Užklausos parametrų perdavimas

forwardParams (nuorodos loginė reikšmė, numatytoji false; nustatoma per POST /links ir PATCH /links/:id, grąžinama per GET /links/:id) prideda visą lankytojo užklausos eilutę prie URL variantų. Lankytojo reikšmės pakeičia išsaugotąsias, įskaitant utm. Failų ir teksto variantai šį nustatymą ignoruoja. Tai maršrutizavimas, o ne prieigos kontrolė: parametrus gali pridėti bet kas. Parametrų reikšmės nesaugomos analitikoje.

Aplankai

Aplankas yra nuoroda, pateikianti į ją įdėtų elementų sąrašą. Modelio aprašymą rasite skiltyje Aplankai.

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_..."
Maršrutas Užklausos turinys Atsakymas
POST /links { "kind": "folder", "name" } ir įprasti nuorodos laukai; be url, text, storageId ar variants sukurtas aplankas
POST /links/:id/move { "folder": "<slug>" } arba { "folder": null } aukščiausiam lygiui, neprivalomas folderDomain { "id", "folder" }
POST /links/:id/copy — { "id", "url", "access", "kind", "variants", "folder", … } (ta pati prieiga, naujas bendrinimo URL, be žmonių)

Perkėlimas ir kopijavimas kiekvienas skaičiuojami kaip vienas įvykis. Nežinomas aplanko slug grąžina 404 (Folder "<slug>" not found); slug, kuris nėra aplankas, arba aplanko perkėlimas į save patį ar į žemiau esantį aplanką grąžina 400. Aplankai gali būti įdėti vienas į kitą ne daugiau kaip 32 lygiais.

Prieiga ir bendrinimas

Kiekviena nuoroda ir aplankas turi access: restricted (numatytasis; savininkas ir prisijungę žmonės, su kuriais ji bendrinama, adresu https://linkdash.dev/s/<token>), link (bet kas, turintis tą URL) arba public (bet kas, trumpuoju URL). Nustatykite jį per POST /links arba PATCH /links/:id. Nuorodoms, skirtoms skelbti viešai, perduokite "access": "public". Kaip veikia aplankai ir peržiūrėtojai, aprašyta skiltyje Bendrinimas ir prieiga.

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_..."
Maršrutas Užklausos turinys Atsakymas
POST /links/:id/shares { "emails": [...] } (1–50 el. pašto adresų) { "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" } (viskas, ką bendrinote)
GET /shared — { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }
DELETE /shared/:id — { "_id", "left": true } (:id yra _id arba bendrinimo žetonas iš GET /shared)
POST /links/:id/reset-link — { "id", "access", "url" }

POST /links/:id/shares priima "role": "editor" redaktoriams. Redaktoriai keičia elementus ir mato statistiką bei veiklą, tačiau niekada negali keisti slaptažodžių, slug, domeno, prieigos, bendrinimo, trinti, perkelti ar kopijuoti (403); kaip :id jie naudoja elemento _id arba bendrinimo žetoną, o slaptažodžiu apsaugotas variantas lieka locked: true, kol neatliekama POST /links/:id/unlock (30 minučių, dešimt neteisingų slaptažodžių per valandą, tada 429). Išsaugojimas po to, kai išsaugojo kitas asmuo, grąžina 409 tik tada, kai užklausoje siunčiamas expectedVersion. Visi bendrinimo maršrutai priima ?domain=, kai slug kartojasi. accepted yra false, kol tas el. pašto adresas neturi patvirtintos paskyros; viaFolder reiškia, kad prieiga gauta per aukščiau esantį aplanką. Iki 200 žmonių vienam elementui ir iki 100 kvietimų el. laiškų vienai paskyrai per dieną. GET /shares ir GET /shared grąžina po vieną puslapį: ?limit= yra 1–100 (numatytoji reikšmė 50); perduokite ?cursor= iš ankstesnio puslapio, kol cursor taps null. Bendrinimas, bendrinimo atšaukimas ir atstatymas kiekvienas skaičiuojami kaip vienas įvykis; išėjimas neskaičiuojamas. Prieiga per aukščiau esantį bendrinamą aplanką išlieka ir išėjus.

Klaidos

Būsena Kada
400 Validavimo klaida, trūksta užklausos turinio, sumaišyti kūrimo tipai
401 Trūksta prieigos rakto (bearer) arba jis neteisingas
404 Nežinomas slug, domenas arba aplankas
409 Slug užimtas (code: "slug_taken")
429 Pasiekta mėnesio įvykių kvota
503 Šiame diegime API raktai nesukonfigūruoti

Šiuos galinius taškus rasite skiltyse webhooks ir pasirinktiniai domenai.

Was this page helpful?