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

HTTP API

REST aadressil https://api.linkdash.dev/v1, autentimiseks armatuurlaualt saadud bearer-võti. Toimingud on samad mis CLI-s ja MCP-s.

Baas-URL: https://api.linkdash.dev/v1

Autentimine: Authorization: Bearer ldash_... (võtmed saad luua lehel Armatuurlaud → API-võtmed). Ära mõtle võtmeid ise välja.

CLI viide: CLI. MCP: MCP. Hinnad / kvoodid: Hinnad. Avastamine (autentimiseta): GET https://api.linkdash.dev/v1. Puhas markdown: api.md.

Avalikud ID-d on slugid (deck, k3m9xq), mitte Convexi _id. JSON-väljade nimed on samad mis CLI stdout’is (id, url, kind, …).

Kokkulepped

  • Kasutusel on JSON Content-Type: application/json, kui pole öeldud teisiti.
  • Loomisel anna täpselt üks järgmistest: url, text või storageId (pärast POST /uploads), või massiiv variants (vt Variandid), või "kind": "folder" koos väljaga name (vt Kaustad). Üleslaadimis-URL-i loomine tagastab { "uploadUrl", "storageId" }. Host saadab baidid PUT-päringuga aadressile uploadUrl. Väikeste failide puhul võid endiselt kasutada multipart-välja file päringus POST /links.
  • Kestused: 7d, 24h, 30m, 1w või ISO-kuupäev. Väljad: expires / expiresAt, starts / startsAt.
  • Avamiste piirang: valikuline positiivne täisarv maxOpenings. Kui link on nii mitu korda edukalt avatud, see peatub. Et link jälle töötaks, tõsta maxOpenings väärtust või kasuta clearMaxOpenings. Kui piirangut pole vaja, jäta maxOpenings ära.
  • Kui sama slug on olemas omaniku kahel domeenil, anna kaasa ?domain= / JSON-väli domain.
  • Vead: { "error": "..." } ja valikuline code. Juba võetud lida.sh slugi korral tuleb vastuseks 409 koos code: "slug_taken".
  • Ligipääs: uued lingid ja kaustad on restricted, kui keha ei määra välja access (vt Ligipääs ja jagamine). Vastustes on url jagamis-URL (https://linkdash.dev/s/<token>). Avaliku lingi puhul on see lühi-URL.
  • Kirjutamistoimingud lähevad kuise sündmuste kvoodi hulka (ka jagamine, jagamise lõpetamine ja lähtestamine). List / get / stats / export / shares list / shared / webhook list/get kvooti ei kuluta. Külastuste / allalaadimiste / esituste registreerimine läheb endiselt arvesse.

Otspunktid

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 (ilma id-ta) 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 (ilma id-ta)
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
(hosti PUT pärast URL-i loomist) 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 ja auth logout on brauseripõhised seadmevood. Need ei ole Unkey marsruudid.

GET /me

Sisselogitud konto. { "userId": "...", "email": "...", "name": "..." }. Kui e-post või nimi pole teada, jäetakse need vastusest välja.

URL-lingi loomine

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-kehas peab olema täpselt üks väljadest url, text või storageId. Lisaks saad anda valikulised väljad access (vaikimisi restricted | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (ainult URL-linkidel) ning folder (+ folderDomain), kui tahad lingi kohe kausta luua. Lühivorm loob ühe variandi nimega main. Ülemise taseme password, starts, expires ja maxOpenings moodustavad lingi värava. Vastus: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.

GET /links tagastab ühe lehekülje kujul { "items": [...], "cursor" }. ?limit= on vahemikus 1-100 (vaikimisi 50). Anna eelmiselt leheküljelt saadud ?cursor= kaasa, kuni see on null. q otsib terveid sõnu (viimast sõna prefiksina) ja järjestab tulemused asjakohasuse järgi. Elemendid on kujul { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (kaustaridadel on lisaks items). kind-filtril on lisaks väärtused folder ja group, status-filtril lisaks mixed. folder=<slug>|root (+ folderDomain) näitab ühe kausta sisu või ülemist taset. GET /links/:id tagastab kogu lingi koos väljadega access ja variants. Sisu (destinationUrl / textContent / fileName) on iga variandi juures eraldi.

Faili üleslaadimine

Loo üleslaadimis-URL ({uploadUrl,storageId}), saada baidid hostist PUT-päringuga ja loo siis samas voos link:

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

Väikeste failide puhul võid endiselt kasutada multiparti päringus POST /links:

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

Valikulised multipart-väljad: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.

Uuendamine, statistika, CSV

PATCH /links/:id võtab vastu JSON-i või multiparti. Faili baitide asendamiseks kasuta storageId-d (pärast POST /uploads ja hosti PUT-i) või multipart-välja file (ainult ühe variandiga linkidel). --status / { "status": "expired" } lükatakse tagasi, kasuta selle asemel expires. Ka { "status": "scheduled" } lükatakse tagasi, kasuta selle asemel starts. Valikuline maxOpenings peatab lingi pärast nii mitut avamist, clearMaxOpenings eemaldab piirangu. sticky (boolean) ja restartSplit (boolean) määravad, kuidas külastajad variantide vahel jaotatakse. forwardParams (boolean) edastab külastaja päringustringi, vt Päringuparameetrite edastamine. access määrab, kes saab linki avada. resetShareLink: true annab lingile uue jagamis-URL-i. Vastus: { "id", "url", "access", "status", "variantStatuses" }.

GET /links/:id/stats?last=24h tagastab väljad visits, downloads, plays, visitsInLast, countries, referrers, variants (iga variandi kogusummad), visitors ja crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]). crawlers näitab botte ja lingieelvaateid, mis on linki laadinud. Neid ei loeta kunagi külastusteks, vt Indekseerijate logi.

GET /links/export tagastab CSV veergudega slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, iga variant eraldi real. folder on kausta slug, kus link asub. access on restricted, link või public. POST /links/import võtab vastu toore CSV või multipart-välja file. Read rühmitatakse slugi ja domeeni järgi: esimene rida loob lingi koos variandiga ja järgmised read lisavad variante. Olemasolevate linkide puhul uuendatakse välju ja seejärel uuendatakse või lisatakse variante nime järgi. Read, kus kind on folder (ja name on olemas), loovad kaustad. Veeru folder järgi paigutatakse lingid kaustadesse alles siis, kui kõik read on loodud. Kui access on tühi, saavad uued lingid väärtuse restricted ja olemasolevad lingid jäävad muutmata.

Kausta kustutamisel saad DELETE /links/:id päringule anda ?contents=keep (vaikimisi: elemendid liiguvad taseme võrra üles) või ?contents=delete (kustutatakse ka kaustas olevad elemendid ja alamkaustad).

Variandid

Iga link sisaldab ühte või mitut varianti. Variandil on sisu (url | file | text), oma värav (password, paused, starts, expires, maxOpenings), kaal weight ja valikulised külastajatingimused when. Lingile endale kuuluvad slug, domeen, nimi, sildid, eelvaade, lingi värav (mis on variantide väravatest tähtsam), sticky (vaikimisi true) ja splitVersion (restartSplit suurendab seda). Kui variants puudub, on lingil üks variant nimega main. Nimes võivad olla väiketähed, numbrid ja sidekriipsud (mitte alguses ega lõpus), pikkus 1–40 märki ning nimi peab lingi piires olema unikaalne. Ühel lingil saab olla kuni 20 varianti.

Iga külastaja saab ühe variandi. Kõigepealt kogutakse variandid, mille when sobib. Kui ükski ei sobi, võetakse tingimusteta variandid. Nende seast valitakse kaalu järgi: kui sticky on sees, määrab valiku külastaja, lingi ja splitVersion-i põhjal arvutatud räsi, muidu on valik juhuslik. Indekseerijad saavad esimese aktiivse tingimusteta variandi. Kui variante on mitu, on lingi kind väärtus group. Lingi status on lingi värava staatus, kui värav on määratud. Muidu on see kõigi variantide ühine staatus ja kui see erineb, siis mixed. variantStatuses loendab { active, paused, expired, scheduled }.

Loo mitu varianti korraga:

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

Iga variandi väljad: name (kohustuslik), üks väljadest url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. Multipart-loomine toetab ainult lühivormi.

Marsruut Keha Vastus
GET /links/:id/variants — variantide massiiv
POST /links/:id/variants JSON või multipart file: name (kohustuslik), sisu, password, starts, expires, maxOpenings, utm, weight, when variant
PATCH /links/:id/variants/:name name (ümbernimetamine), 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 } (viimast varianti ei saa kustutada)

when võtmed (väärtused on stringide massiivid ja iga määratud võti peab sobima): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (prefiks), referrerHosts (hosti sufiks).

Päringuparameetrite reeglid

when.params on massiiv kuni 10 reegliga, mis kontrollivad külastaja päringustringi (lida.sh/promo?src=newsletter). Kõik reeglid peavad kehtima. Iga reegel on kujul { "key", "op", "value" } ja op on üks järgmistest: equals | notEquals | includes | startsWith | endsWith | in (value on |-ga või komaga eraldatud loend) | exists | missing. value on kohustuslik, välja arvatud exists / missing puhul. Võtmed on tõstutundlikud ja väärtused peavad täpselt kattuma.

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

Parameetrite väärtusi kontrollitakse lingi avamise hetkel ja neid ei salvestata kunagi analüütikasse.

Päringuparameetrite edastamine

forwardParams on lingi boolean-väli, vaikimisi false. Saad selle määrata päringutes POST /links ja PATCH /links/:id ning GET /links/:id tagastab selle. Kui see on sees, lisatakse URL-variantidele kogu külastaja päringustring. Külastaja väärtused kirjutavad salvestatud väärtused üle, ka utm. Faili- ja tekstivariandid seda ei arvesta. See on suunamine, mitte ligipääsukontroll: parameetreid saab lisada igaüks. Parameetrite väärtusi analüütikasse ei salvestata.

Kaustad

Kaust on link, mis näitab sinna pandud elemente. Mudeli kohta loe lähemalt lehelt Kaustad.

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_..."
Marsruut Keha Vastus
POST /links { "kind": "folder", "name" } ja tavalised lingiväljad, aga ilma väljadeta url, text, storageId ja variants loodud kaust
POST /links/:id/move { "folder": "<slug>" } või ülemise taseme jaoks { "folder": null }, valikuline folderDomain { "id", "folder" }
POST /links/:id/copy — { "id", "url", "access", "kind", "variants", "folder", … } (sama ligipääs, uus jagamis-URL, inimesi ei kopeerita)

Liigutamine ja kopeerimine lähevad kumbki arvesse ühe sündmusena. Tundmatu kausta slugi korral tuleb vastuseks 404 (Folder "<slug>" not found). Kui slug ei kuulu kaustale või proovid kausta liigutada iseendasse või oma alamkausta, tuleb vastuseks 400. Kaustu saab pesastada kuni 32 taseme sügavuseni.

Ligipääs ja jagamine

Igal lingil ja kaustal on väli access. restricted (vaikimisi) tähendab, et avada saavad omanik ja inimesed, kellega link on jagatud. Nad peavad olema sisse logitud ja link asub aadressil https://linkdash.dev/s/<token>. link tähendab, et avada saab igaüks, kellel see URL on. public tähendab, et avada saab igaüks lühi-URL-i kaudu. Määra ligipääs päringus POST /links või PATCH /links/:id. Kui link on mõeldud avalikult postitamiseks, anna "access": "public". Kaustade ja vaatajate kohta loe lähemalt lehelt Jagamine ja ligipääs.

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_..."
Marsruut Keha Vastus
POST /links/:id/shares { "emails": [...] } (1–50 e-posti aadressi) { "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" } (kõik, mida oled jaganud)
GET /shared — { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }
DELETE /shared/:id — { "_id", "left": true } (:id on _id või jagamistoken vastusest GET /shared)
POST /links/:id/reset-link — { "id", "access", "url" }

Toimetaja lisamiseks anna päringule POST /links/:id/shares väli "role": "editor". Toimetajad saavad elemente muuta ning näevad statistikat ja tegevuslogi. Paroole, slugi, domeeni, ligipääsu ega jagamist nad muuta ei saa, samuti ei saa nad kustutada, liigutada ega kopeerida (403). Toimetaja kasutab :id-na elemendi _id-d või jagamistokenit. Parooliga kaitstud variant jääb olekusse locked: true, kuni see avatakse päringuga POST /links/:id/unlock. Avamine kehtib 30 minutit ja tunnis on lubatud kümme valet parooli, pärast seda tuleb 429. Kui keegi teine on vahepeal salvestanud, saad salvestamisel 409, aga ainult siis, kui päring saadab expectedVersion. Kõik jagamismarsruudid võtavad vastu ?domain=, kui sama slug esineb mitmel domeenil. accepted on false, kuni sellel e-posti aadressil on kinnitatud konto. viaFolder tähendab, et ligipääs tuleb ülemisest kaustast. Ühe elemendiga saab jagada kuni 200 inimest ja üks konto saab päevas saata kuni 100 kutsekirja. GET /shares ja GET /shared tagastavad tulemused lehekülgede kaupa. ?limit= on vahemikus 1-100 (vaikimisi 50). Anna eelmiselt leheküljelt saadud ?cursor= kaasa, kuni cursor on null. Jagamine, jagamise lõpetamine ja lähtestamine lähevad igaüks arvesse ühe sündmusena, lahkumine mitte. Kui ligipääs tuleb jagatud ülemise kausta kaudu, jääb see pärast lahkumist alles.

Vead

Olek Millal
400 Valideerimisviga, keha puudub või loomisel on segatud eri tüüpe
401 Bearer-võti puudub või on kehtetu
404 Tundmatu slug, domeen või kaust
409 Slug on juba võetud (code: "slug_taken")
429 Kuine sündmuste kvoot on täis
503 Selles juurutuses pole API-võtmeid seadistatud

Nende otspunktide kohta loe lähemalt lehtedelt webhookid ja kohandatud domeenid.

Was this page helpful?