---
title: API HTTP
description: >-
  REST la https://api.linkdash.dev/v1 cu o cheie bearer din dashboard. Aceleași
  operații ca în CLI și MCP.
sidebar:
  label: API HTTP
  order: 4
---
URL de bază: `https://api.linkdash.dev/v1`

Autentificare: `Authorization: Bearer ldash_...` (creează chei în [Dashboard → Chei API](https://linkdash.dev/dashboard/keys)). Nu inventa chei.

Referință CLI: [CLI](/ro/cli). MCP: [MCP](/ro/mcp). Prețuri / cote: [Prețuri](/ro/pricing). Descoperire (fără autentificare): `GET https://api.linkdash.dev/v1`. Markdown simplu: [api.md](https://linkdash.dev/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](#variants)), **sau** `"kind": "folder"` cu un `name` (vezi [Foldere](#folders)). 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](#access-and-sharing)). `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" }` | `{ "id", "email", "role" }` |
| `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

```bash
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:

```bash
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`:

```bash
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](#forward-query-parameters). `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](https://linkdash.dev/pricing.md)).

`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ă:

```bash
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.

```json
{ "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](/ro/folders) pentru detalii despre model.

```bash
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](/ro/sharing) ca să afli cum funcționează folderele și vizualizatorii.

```bash
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](/ro/webhooks) și [domenii personalizate](/ro/domains) pentru acele endpointuri.
