HTTP API
REST na https://api.linkdash.dev/v1 s bearer ključem s nadzorne ploče. Iste operacije kao CLI i MCP.
Osnovni URL: https://api.linkdash.dev/v1
Autentifikacija: Authorization: Bearer ldash_... (ključeve izradite na Nadzorna ploča → API ključevi). Ne izmišljajte ključeve.
CLI referenca: CLI. MCP: MCP. Cijene / kvote: Cijene. Otkrivanje (bez autentifikacije): GET https://api.linkdash.dev/v1. Običan markdown: api.md.
Javni identifikatori su slugovi (deck, k3m9xq), a ne Convex _id. Nazivi JSON polja odgovaraju CLI stdoutu (id, url, kind, …).
Konvencije
- JSON
Content-Type: application/jsonosim ako nije drukčije navedeno. - Izrada prima točno jedno od
url,textilistorageIdnakonPOST /uploads, ili poljevariants(pogledajte Varijante), ili"kind": "folder"sname(pogledajte Mape). Izdavanje URL-a za prijenos vraća{ "uploadUrl", "storageId" }. Host PUT-om šalje bajtove nauploadUrl. Male datoteke i dalje mogu koristiti multipartfilenaPOST /links. - Trajanja:
7d,24h,30m,1wili ISO datum. Polja:expires/expiresAt,starts/startsAt. - Ograničenje otvaranja: neobavezni pozitivni cijeli broj
maxOpenings. Poveznica se pauzira nakon toliko uspješnih otvaranja. PovećajtemaxOpeningsili pošaljiteclearMaxOpeningskako bi se ponovno posluživala. IzostavitemaxOpeningsza neograničen broj otvaranja. - Ako slug postoji na dvije vlasnikove domene, proslijedite
?domain=/ JSONdomain. - Pogreške:
{ "error": "..." }uz neobaveznicode. Zauzetilida.shslugovi vraćaju409scode: "slug_taken". - Pristup: nove poveznice i mape su
restrictedosim ako tijelo zahtjeva ne postaviaccess(pogledajte Pristup i dijeljenje).urlu odgovorima je URL za dijeljenje (https://linkdash.dev/s/<token>), osim ako je poveznica javna, kada je to kratki URL. - Operacije pisanja ubrajaju se u mjesečnu kvotu događaja (uključujući dijeljenje, prekid dijeljenja i resetiranje). Popis / dohvat / statistika / izvoz / popis dijeljenja / podijeljeno / popis i dohvat webhookova ne ubrajaju se. Unos posjeta / preuzimanja / reprodukcija i dalje se ubraja.
Krajnje 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 (bez id-a) |
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 (bez 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 s hosta nakon izdavanja) | 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 i auth logout tokovi su autorizacije uređaja putem preglednika. Nisu Unkey rute.
GET /me
Prijavljeni račun. { "userId": "...", "email": "...", "name": "..." }. E-pošta i ime izostavljaju se kada nisu poznati.
Izrada URL poveznice
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 tijelo prima točno jedno od url, text ili storageId, uz neobavezne access (restricted zadano | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (samo za URL poveznice) te folder (+ folderDomain) za izradu unutar mape. Skraćeni oblik izrađuje jednu varijantu naziva main; password, starts, expires i maxOpenings na najvišoj razini čine zaštitu poveznice. Odgovor: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.
GET /links vraća jednu stranicu, { "items": [...], "cursor" }: ?limit= je 1-100 (zadano 50); prosljeđujte ?cursor= s prethodne stranice dok ne bude null. q pronalazi podudaranja cijelih riječi (posljednje kao prefiksa), rangirana prema relevantnosti. Stavke su { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (retci mapa dodaju items); filtar kind dodaje folder i group, filtar status dodaje mixed, a folder=<slug>|root (+ folderDomain) ispisuje jednu mapu ili najvišu razinu. GET /links/:id vraća cijelu poveznicu s access i variants; sadržaj (destinationUrl / textContent / fileName) nalazi se na svakoj varijanti.
Prijenos datoteke
Izdajte URL za prijenos ({uploadUrl,storageId}), PUT-om pošaljite bajtove s hosta, a zatim izradite poveznicu u istom toku:
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}'
Male datoteke i dalje mogu koristiti 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"
Neobavezna multipart polja: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.
Ažuriranje, statistika, CSV
PATCH /links/:id prima JSON ili multipart. Bajtove datoteke zamijenite s storageId nakon POST /uploads + PUT-a s hosta ili multipart poljem file (samo za poveznice s jednom varijantom). --status / { "status": "expired" } se odbija — koristite expires. { "status": "scheduled" } se odbija — koristite starts. Neobavezni maxOpenings pauzira poveznicu nakon toliko otvaranja; clearMaxOpenings uklanja ograničenje. sticky (boolean) i restartSplit (boolean) upravljaju dodjelom varijanti; forwardParams (boolean) prosljeđuje posjetiteljev query string, pogledajte Prosljeđivanje query parametara. access mijenja tko je može otvoriti; resetShareLink: true izdaje novi URL za dijeljenje. Odgovor: { "id", "url", "access", "status", "variantStatuses" }.
GET /links/:id/stats?last=24h vraća visits, downloads, plays, visitsInLast, countries, referrers, variants (ukupni zbrojevi po varijanti), visitors i crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: botovi i pregledi poveznica koji su dohvatili poveznicu, a nikada se ne broje kao posjeti; pogledajte Zapisnik crawlera).
GET /links/export vraća CSV sa stupcima slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, jedan redak po varijanti (folder je slug mape u kojoj se poveznica nalazi; access je restricted, link ili public). POST /links/import prihvaća sirovi CSV ili multipart file; retci se grupiraju prema slugu + domeni (prvi redak izrađuje poveznicu s njezinom varijantom, daljnji retci dodaju varijante; postojećim poveznicama ažuriraju se polja, a zatim se varijante ažuriraju ili dodaju prema nazivu). Retci s kind folder (s name) izrađuju mape, a stupac folder smješta poveznice nakon što su obrađeni svi retci. Prazan access nove poveznice čini ograničenima, a postojeće ostavlja nepromijenjenima.
DELETE /links/:id na mapi prima ?contents=keep (zadano: stavke se premještaju jednu razinu više) ili ?contents=delete (brišu se i stavke i mape unutar nje).
Varijante
Svaka poveznica spremnik je jedne ili više varijanti: sadržaja (url | file | text) s vlastitom zaštitom (password, paused, starts, expires, maxOpenings), težinom weight i neobaveznim uvjetima za posjetitelje when. Poveznici pripadaju slug, domena, naziv, oznake, pregled, vlastita zaštita (koja ima prednost pred zaštitama varijanti), sticky (zadano true) i splitVersion (povećava ga restartSplit). Bez variants poveznica ima jednu varijantu naziva main. Nazivi: mala slova, znamenke, unutarnje crtice, 1–40 znakova, jedinstveni unutar poveznice. Najviše 20 varijanti po poveznici.
Posjetitelj dobiva jednu varijantu: varijante čiji se when podudara čine skup za odabir (ako se nijedna ne podudara, skup čine bezuvjetne varijante), a zatim slijedi ponderirani odabir (sticky hash posjetitelja + poveznice + splitVersion, inače nasumično). Crawleri dobivaju prvu aktivnu bezuvjetnu varijantu. kind poveznice je group kada ima više varijanti. status poveznice je status zaštite poveznice kada je postavljena, inače status koji dijele sve varijante, inače mixed. variantStatuses broji { active, paused, expired, scheduled }.
Izradite više varijanti odjednom:
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"]}}]}'
Svaka varijanta: name (obavezno), jedno od url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. Izrada putem multiparta podržava samo skraćeni oblik.
| Ruta | Tijelo | Odgovor |
|---|---|---|
GET /links/:id/variants |
— | polje varijanti |
POST /links/:id/variants |
JSON ili multipart file: name (obavezno), sadržaj, password, starts, expires, maxOpenings, utm, weight, when |
varijanta |
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 |
varijanta |
DELETE /links/:id/variants/:name |
— | { "id", "variant", "deleted": true } (posljednja varijanta ne može se izbrisati) |
Ključevi when (polja nizova znakova; svaki postavljeni ključ mora se podudarati): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (prefiks), referrerHosts (sufiks hosta).
Pravila za query parametre
when.params je polje od najviše 10 pravila nad posjetiteljevim query stringom (lida.sh/promo?src=newsletter); sva pravila moraju biti zadovoljena. Svako pravilo ima oblik { "key", "op", "value" }, pri čemu je op jedno od equals | notEquals | includes | startsWith | endsWith | in (value je popis odvojen znakom | ili zarezom) | exists | missing. value je obavezan, osim za exists / missing. Ključevi razlikuju velika i mala slova, a vrijednosti se uspoređuju doslovno.
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
Vrijednosti parametara provjeravaju se u trenutku otvaranja i nikada se ne pohranjuju u analitici.
Prosljeđivanje query parametara
forwardParams (boolean na poveznici, zadano false; može se postaviti na POST /links i PATCH /links/:id, a vraća ga GET /links/:id) dodaje cijeli posjetiteljev query string URL varijantama. Posjetiteljeve vrijednosti nadjačavaju pohranjene, uključujući utm. Varijante s datotekom i tekstom zanemaruju ovu postavku. Ovo je usmjeravanje, a ne kontrola pristupa: svatko može dodati parametre. Vrijednosti parametara ne pohranjuju se u analitici.
Mape
Mapa je poveznica koja ispisuje stavke koje u nju stavite. Za opis modela pogledajte 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_..."
| Ruta | Tijelo | Odgovor |
|---|---|---|
POST /links |
{ "kind": "folder", "name" } uz uobičajena polja poveznice; bez url, text, storageId ili variants |
izrađena mapa |
POST /links/:id/move |
{ "folder": "<slug>" } ili { "folder": null } za najvišu razinu, neobavezno folderDomain |
{ "id", "folder" } |
POST /links/:id/copy |
— | { "id", "url", "access", "kind", "variants", "folder", … } (isti pristup, novi URL za dijeljenje, bez osoba) |
Premještanje i kopiranje broje se svako kao jedan događaj. Nepoznati slug mape vraća 404 (Folder "<slug>" not found); slug koji nije mapa, kao i premještanje mape u samu sebe ili u mapu ispod nje, vraća 400. Mape se mogu ugnježđivati najviše 32 razine duboko.
Pristup i dijeljenje
Svaka poveznica i mapa ima access: restricted (zadano; vlasnik i osobe s kojima je podijeljena, uz prijavu, na https://linkdash.dev/s/<token>), link (svatko s tim URL-om) ili public (svatko, na kratkom URL-u). Postavite ga na POST /links ili PATCH /links/:id. Proslijedite "access": "public" za poveznice namijenjene javnom objavljivanju. Kako funkcioniraju mape i gledatelji, pogledajte u Dijeljenje i pristup.
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_..."
| Ruta | Tijelo | Odgovor |
|---|---|---|
POST /links/:id/shares |
{ "emails": [...] } (1–50 adresa e-pošte) |
{ "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" } (sve što ste podijelili) |
GET /shared |
— | { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" } |
DELETE /shared/:id |
— | { "_id", "left": true } (:id je _id ili token za dijeljenje iz GET /shared) |
POST /links/:id/reset-link |
— | { "id", "access", "url" } |
POST /links/:id/shares prima "role": "editor" za urednike. Urednici mijenjaju stavke te vide statistiku i aktivnost, ali nemaju pristup lozinkama, slugu, domeni, pristupu, dijeljenju, brisanju, premještanju ni kopiranju (403); kao :id koriste _id stavke ili token za dijeljenje, a varijanta zaštićena lozinkom ostaje locked: true do poziva POST /links/:id/unlock (30 minuta, deset pogrešnih lozinki na sat, zatim 429). Spremanje nakon što je netko drugi već spremio vraća 409 samo kada zahtjev šalje expectedVersion. Sve rute za dijeljenje primaju ?domain= kada se slug ponavlja. accepted je false dok ta adresa e-pošte nema potvrđeni račun; viaFolder znači da pristup proizlazi iz nadređene mape. Najviše 200 osoba po stavci i 100 e-poruka s pozivnicom po računu dnevno. GET /shares i GET /shared vraćaju po jednu stranicu: ?limit= je 1-100 (zadano 50); prosljeđujte ?cursor= s prethodne stranice dok cursor ne bude null. Dijeljenje, prekid dijeljenja i resetiranje broje se svako kao jedan događaj; napuštanje se ne broji. Pristup putem podijeljene nadređene mape ostaje i nakon napuštanja.
Pogreške
| Status | Kada |
|---|---|
| 400 | Validacija, nedostaje tijelo zahtjeva, pomiješane vrste izrade |
| 401 | Bearer ključ nedostaje ili je nevažeći |
| 404 | Nepoznati slug, domena ili mapa |
| 409 | Slug je zauzet (code: "slug_taken") |
| 429 | Dosegnuta je mjesečna kvota događaja |
| 503 | API ključevi nisu konfigurirani na ovoj implementaciji |
Za te krajnje točke pogledajte webhookove i prilagođene domene.

