API HTTP
REST la https://api.linkdash.dev/v1 cu o cheie bearer din dashboard. Aceleași operații ca în CLI și MCP.
URL de bază: https://api.linkdash.dev/v1
Autentificare: Authorization: Bearer ldash_... (creează chei în Dashboard → Chei API). Nu inventa chei.
Referință CLI: CLI. MCP: MCP. Prețuri / cote: Prețuri. Descoperire (fără autentificare): GET https://api.linkdash.dev/v1. Markdown simplu: api.md.
ID-urile publice sunt slug-uri (deck, k3m9xq), nu _id din Convex. Numele câmpurilor JSON corespund cu stdout-ul CLI (id, url, kind, …).
Convenții
- JSON
Content-Type: application/json, dacă nu se specifică altfel. - Crearea primește exact unul dintre
url,textsaustorageIddupăPOST /uploads, sau un arrayvariants(vezi Variante), sau"kind": "folder"cu unname(vezi Foldere). Generarea URL-ului de upload returnează{ "uploadUrl", "storageId" }. Host-ul face PUT cu octeții lauploadUrl. Fișierele mici pot folosi în continuare multipartfilepePOST /links. - Durate:
7d,24h,30m,1wsau o dată ISO. Câmpuri:expires/expiresAt,starts/startsAt. - Limită de deschideri:
maxOpeningsopțional, număr întreg pozitiv. Linkul intră pe pauză după atâtea deschideri reușite. MăreștemaxOpeningssau foloseșteclearMaxOpeningsca să-l servești din nou. OmitemaxOpeningspentru nelimitat. - Dacă un slug există pe două dintre domeniile proprietarului, trimite
?domain=/domainîn JSON. - Erori:
{ "error": "..." }pluscodeopțional. Slug-urilelida.shocupate returnează409cucode: "slug_taken". - Acces: linkurile și folderele noi sunt
restricted, cu excepția cazului în care body-ul seteazăaccess(vezi Acces și partajare).urldin răspunsuri este URL-ul de partajare (https://linkdash.dev/s/<token>), cu excepția cazului în care linkul e public; atunci e URL-ul scurt. - Scrierile se contorizează în cota lunară de evenimente (inclusiv share, unshare și reset). List / get / stats / export / listarea share-urilor / shared / webhook list/get nu se contorizează. Ingestia de visit / download / play se contorizează în continuare.
Endpointuri
| 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 (fără 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 (fără 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 de la host după generarea URL-ului) | 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 sunt fluxuri de autentificare a dispozitivului prin browser. Nu sunt rute Unkey.
GET /me
Contul autentificat. { "userId": "...", "email": "...", "name": "..." }. Email-ul și numele sunt omise când nu sunt cunoscute.
Creează un link 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"}'
Body-ul JSON primește exact unul dintre url, text sau storageId, plus opțional access (restricted implicit | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (doar pentru linkuri URL) și folder (+ folderDomain) ca să creezi linkul într-un folder. Forma scurtă creează o variantă numită main; password, starts, expires și maxOpenings de la nivelul superior formează poarta de acces a linkului. Răspuns: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.
GET /links returnează o pagină, { "items": [...], "cursor" }: ?limit= este 1-100 (implicit 50); trimite ?cursor= de la pagina anterioară până devine null. q caută cuvinte întregi (ultimul ca prefix), cu rezultatele ordonate după relevanță. Elementele sunt { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (rândurile de folder adaugă items); filtrul kind adaugă folder și group, filtrul status adaugă mixed, iar folder=<slug>|root (+ folderDomain) listează un folder sau nivelul superior. GET /links/:id returnează linkul complet cu access și variants; conținutul (destinationUrl / textContent / fileName) se află pe fiecare variantă.
Încarcă un fișier
Generează un URL de upload ({uploadUrl,storageId}), fă PUT cu octeții de pe host, apoi creează linkul în același flux:
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}'
Fișierele mici pot folosi în continuare multipart pe POST /links:
curl https://api.linkdash.dev/v1/links \
-H "Authorization: Bearer ldash_..." \
-F "file=@./deck.pdf" \
-F "expires=7d" \
-F "slug=deck"
Câmpuri multipart opționale: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.
Actualizare, statistici, CSV
PATCH /links/:id acceptă JSON sau multipart. Înlocuiește octeții fișierului cu storageId după POST /uploads + PUT de pe host, sau cu câmpul multipart file (doar pentru linkuri cu o singură variantă). --status / { "status": "expired" } este respins — folosește expires. { "status": "scheduled" } este respins — folosește starts. maxOpenings opțional pune linkul pe pauză după atâtea deschideri; clearMaxOpenings elimină limita. sticky (boolean) și restartSplit (boolean) controlează atribuirea variantelor; forwardParams (boolean) transmite mai departe query string-ul vizitatorului, vezi Transmiterea parametrilor de query. access schimbă cine îl poate deschide; resetShareLink: true emite un URL de partajare nou. Răspuns: { "id", "url", "access", "status", "variantStatuses" }.
GET /links/:id/stats?last=24h returnează visits, downloads, plays, visitsInLast, countries, referrers, variants (totaluri per variantă), visitors și crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: boți și previzualizări de linkuri care au accesat linkul, niciodată contorizate ca vizite; vezi Jurnalul crawlerelor).
GET /links/export returnează CSV cu coloanele slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, câte un rând per variantă (folder este slug-ul folderului care îl conține; access este restricted, link sau public). POST /links/import acceptă CSV brut sau multipart file; rândurile sunt grupate după slug + domeniu (primul rând creează linkul cu varianta sa, rândurile următoare adaugă variante; linkurile existente își actualizează câmpurile, apoi actualizează sau adaugă variante după nume). Rândurile cu kind folder (cu un name) creează foldere, iar coloana folder plasează linkurile după ce toate rândurile există. Un access gol face linkurile noi restricționate și le lasă pe cele existente neschimbate.
DELETE /links/:id pe un folder acceptă ?contents=keep (implicit: elementele urcă un nivel) sau ?contents=delete (elementele și folderele din interior sunt șterse și ele).
Variante
Fiecare link este un container pentru una sau mai multe variante: conținut (url | file | text) plus propria poartă de acces (password, paused, starts, expires, maxOpenings), un weight și condiții opționale pentru vizitator, when. Linkul deține slug-ul, domeniul, numele, tag-urile, preview-ul, propria poartă de acces (care are prioritate față de porțile variantelor), sticky (implicit true) și splitVersion (incrementat de restartSplit). Fără variants, un link are o singură variantă numită main. Nume: litere mici, cifre, cratime interne, 1–40 de caractere, unice per link. Maximum 20 de variante per link.
Un vizitator primește o singură variantă: variantele al căror when se potrivește formează pool-ul (dacă niciuna nu se potrivește, îl formează variantele necondiționate), apoi urmează o alegere ponderată (hash sticky din vizitator + link + splitVersion, altfel aleator). Crawlerele primesc prima variantă necondiționată activă. kind al linkului este group când are mai multe variante. status al linkului este cel al porții linkului când e setată, altfel statusul comun al tuturor variantelor, altfel mixed. variantStatuses numără { active, paused, expired, scheduled }.
Creează mai multe variante deodată:
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"]}}]}'
Fiecare variantă: name (obligatoriu), unul dintre url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. Crearea prin multipart rămâne disponibilă doar în forma scurtă.
| Rută | Body | Răspuns |
|---|---|---|
GET /links/:id/variants |
— | array de variante |
POST /links/:id/variants |
JSON sau multipart file: name (obligatoriu), conținut, password, starts, expires, maxOpenings, utm, weight, when |
varianta |
PATCH /links/:id/variants/:name |
name (redenumire), url, text, storageId / file, password, clearPassword, starts, clearStarts, expires, clearExpires, maxOpenings, clearMaxOpenings, status (active | paused), weight, when, clearWhen, utm |
varianta |
DELETE /links/:id/variants/:name |
— | { "id", "variant", "deleted": true } (ultima variantă nu poate fi ștearsă) |
Chei when (array-uri de string-uri; fiecare cheie setată trebuie să se potrivească): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (prefix), referrerHosts (sufix de host).
Reguli pentru parametrii de query
when.params este un array de până la 10 reguli aplicate query string-ului vizitatorului (lida.sh/promo?src=newsletter); toate regulile trebuie să fie îndeplinite. Fiecare regulă este { "key", "op", "value" }, cu op unul dintre equals | notEquals | includes | startsWith | endsWith | in (value este o listă separată prin | sau prin virgulă) | exists | missing. value este obligatoriu, cu excepția exists / missing. Cheile sunt case-sensitive, iar valorile se compară exact.
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
Valorile parametrilor sunt verificate la momentul deschiderii și nu sunt stocate niciodată în analytics.
Transmiterea parametrilor de query
forwardParams (boolean pe link, implicit false; se poate seta pe POST /links și PATCH /links/:id, returnat de GET /links/:id) adaugă întregul query string al vizitatorului la variantele URL. Valorile vizitatorului le suprascriu pe cele stocate, inclusiv utm. Variantele de tip fișier și text îl ignoră. Asta e rutare, nu control al accesului: oricine poate adăuga parametri. Valorile parametrilor nu sunt stocate în analytics.
Foldere
Un folder este un link care listează elementele pe care le pui în el. Vezi Foldere pentru detalii despre model.
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_..."
| Rută | Body | Răspuns |
|---|---|---|
POST /links |
{ "kind": "folder", "name" } plus câmpurile obișnuite ale unui link; fără url, text, storageId sau variants |
folderul creat |
POST /links/:id/move |
{ "folder": "<slug>" } sau { "folder": null } pentru nivelul superior, folderDomain opțional |
{ "id", "folder" } |
POST /links/:id/copy |
— | { "id", "url", "access", "kind", "variants", "folder", … } (același acces, URL de partajare nou, fără persoane) |
Mutarea și copierea se contorizează fiecare ca un eveniment. Un slug de folder necunoscut returnează 404 (Folder "<slug>" not found); un slug care nu e folder, sau mutarea unui folder în el însuși ori într-un folder de sub el, returnează 400. Folderele pot fi imbricate pe cel mult 32 de niveluri.
Acces și partajare
Fiecare link și folder are access: restricted (implicit; proprietarul și persoanele cu care e partajat, autentificate, la https://linkdash.dev/s/<token>), link (oricine are acel URL) sau public (oricine, la URL-ul scurt). Setează-l pe POST /links sau PATCH /links/:id. Trimite "access": "public" pentru linkurile pe care vrei să le postezi public. Vezi Partajare și acces ca să afli cum funcționează folderele și vizualizatorii.
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_..."
| Rută | Body | Răspuns |
|---|---|---|
POST /links/:id/shares |
{ "emails": [...] } (1–50 de emailuri) |
{ "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" } (tot ce ai partajat) |
GET /shared |
— | { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" } |
DELETE /shared/:id |
— | { "_id", "left": true } (:id este _id-ul sau tokenul de partajare din GET /shared) |
POST /links/:id/reset-link |
— | { "id", "access", "url" } |
POST /links/:id/shares acceptă "role": "editor" pentru editori. Editorii modifică elementele și văd statisticile și activitatea, dar nu pot atinge niciodată parolele, slug-ul, domeniul, accesul, partajarea și nu pot șterge, muta sau copia (403); ei folosesc _id-ul elementului sau tokenul de partajare ca :id, iar o variantă protejată cu parolă rămâne locked: true până la POST /links/:id/unlock (30 de minute; după zece parole greșite într-o oră, 429). Salvarea după ce altcineva a salvat între timp dă 409 doar când cererea trimite expectedVersion. Toate rutele de partajare acceptă ?domain= când slug-ul se repetă. accepted este false până când acel email are un cont verificat; viaFolder înseamnă că accesul vine de la un folder de deasupra. Maximum 200 de persoane per element și 100 de emailuri de invitație per cont pe zi. GET /shares și GET /shared returnează câte o pagină: ?limit= este 1-100 (implicit 50); trimite ?cursor= de la pagina anterioară până când cursor este null. Share, unshare și reset se contorizează fiecare ca un eveniment; părăsirea nu. Accesul printr-un folder partajat de deasupra rămâne și după ce părăsești elementul.
Erori
| Status | Când |
|---|---|
| 400 | Validare eșuată, body lipsă, tipuri de creare amestecate |
| 401 | Cheie bearer lipsă sau invalidă |
| 404 | Slug, domeniu sau folder necunoscut |
| 409 | Slug ocupat (code: "slug_taken") |
| 429 | Cota lunară de evenimente a fost atinsă |
| 503 | Cheile API nu sunt configurate pe acest deployment |
Vezi webhooks și domenii personalizate pentru acele endpointuri.

