Sari la conținut
LinkdashLinkdash
Română
Esc
↑↓navighează↵deschide⌘Jprevizualizează
Pe această pagină

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, text sau storageId după POST /uploads, sau un array variants (vezi Variante), sau "kind": "folder" cu un name (vezi Foldere). Generarea URL-ului de upload returnează { "uploadUrl", "storageId" }. Host-ul face PUT cu octeții la uploadUrl. Fișierele mici pot folosi în continuare multipart file pe POST /links.
  • Durate: 7d, 24h, 30m, 1w sau o dată ISO. Câmpuri: expires / expiresAt, starts / startsAt.
  • Limită de deschideri: maxOpenings opțional, număr întreg pozitiv. Linkul intră pe pauză după atâtea deschideri reușite. Mărește maxOpenings sau folosește clearMaxOpenings ca să-l servești din nou. Omite maxOpenings pentru nelimitat.
  • Dacă un slug există pe două dintre domeniile proprietarului, trimite ?domain= / domain în JSON.
  • Erori: { "error": "..." } plus code opțional. Slug-urile lida.sh ocupate returnează 409 cu code: "slug_taken".
  • Acces: linkurile și folderele noi sunt restricted, cu excepția cazului în care body-ul setează access (vezi Acces și partajare). url din 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.

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.

Ți-a fost utilă această pagină?