Skip to content
LinkdashLinkdash
Slovenščina
Esc
↑↓navigate↵open⌘Jpreview
On this page

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, text ali storageId po POST /uploads, ali polje variants (glejte Različice), ali "kind": "folder" z name (glejte Mape). Ustvarjanje URL-ja za nalaganje vrne { "uploadUrl", "storageId" }. Gostitelj z ukazom PUT pošlje bajte na uploadUrl. Majhne datoteke lahko še vedno uporabijo multipart file na POST /links.
  • Trajanja: 7d, 24h, 30m, 1w ali datum ISO. Polja: expires / expiresAt, starts / startsAt.
  • Omejitev odpiranj: izbirno pozitivno celo število maxOpenings. Povezava se po toliko uspešnih odpiranjih zaustavi. Povečajte maxOpenings ali uporabite clearMaxOpenings, da jo znova strežete. Za neomejeno število odpiranj izpustite maxOpenings.
  • Če slug obstaja na dveh lastnikovih domenah, podajte ?domain= / JSON domain.
  • Napake: { "error": "..." } in izbirno code. Zasedeni slugi lida.sh vrnejo 409 s code: "slug_taken".
  • Dostop: nove povezave in mape so restricted, razen če telo nastavi access (glejte Dostop in deljenje). url v 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.

Was this page helpful?