---
title: HTTP API
description: >-
  REST adresu https://api.linkdash.dev/v1 su prieigos raktu (bearer) iš valdymo
  skydelio. Tos pačios operacijos kaip CLI ir MCP.
sidebar:
  label: HTTP API
  order: 4
---
Bazinis URL: `https://api.linkdash.dev/v1`

Autentifikacija: `Authorization: Bearer ldash_...` (raktus sukurkite skiltyje [Valdymo skydelis → API raktai](https://linkdash.dev/dashboard/keys)). Neišgalvokite raktų.

CLI žinynas: [CLI](/lt/cli). MCP: [MCP](/lt/mcp). Kainos / kvotos: [Kainos](/lt/pricing). Aptikimas (be autentifikacijos): `GET https://api.linkdash.dev/v1`. Grynasis markdown: [api.md](https://linkdash.dev/api.md).

Vieši identifikatoriai yra slug reikšmės (`deck`, `k3m9xq`), o ne Convex `_id`. JSON laukų pavadinimai atitinka CLI stdout išvestį (`id`, `url`, `kind`, …).

## Konvencijos

- JSON `Content-Type: application/json`, jei nenurodyta kitaip.
- Kūrimo užklausa priima lygiai vieną iš `url`, `text` arba `storageId` (po `POST /uploads`), **arba** `variants` masyvą (žr. [Variantai](#variants)), **arba** `"kind": "folder"` su `name` (žr. [Aplankai](#folders)). Išdavimas grąžina `{ "uploadUrl", "storageId" }`. Pagrindinė sistema baitus siunčia PUT užklausa į `uploadUrl`. Mažiems failams vis dar galima naudoti multipart lauką `file` su `POST /links`.
- Trukmės: `7d`, `24h`, `30m`, `1w` arba ISO data. Laukai: `expires` / `expiresAt`, `starts` / `startsAt`.
- Atidarymų limitas: neprivalomas teigiamas sveikasis skaičius `maxOpenings`. Nuoroda pristabdoma po tiek sėkmingų atidarymų. Padidinkite `maxOpenings` arba naudokite `clearMaxOpenings`, kad nuoroda vėl būtų pasiekiama. Jei limito nereikia, `maxOpenings` nenurodykite.
- Jei slug egzistuoja dviejuose savininko domenuose, perduokite `?domain=` / JSON `domain`.
- Klaidos: `{ "error": "..." }` ir neprivalomas `code`. Užimti `lida.sh` slug grąžina `409` su `code: "slug_taken"`.
- Prieiga: naujos nuorodos ir aplankai yra `restricted`, nebent užklausos turinyje nustatytas `access` (žr. [Prieiga ir bendrinimas](#access-and-sharing)). Atsakymuose `url` yra bendrinimo URL (`https://linkdash.dev/s/<token>`), nebent nuoroda yra vieša, tada tai trumpasis URL.
- Rašymo operacijos įskaičiuojamos į mėnesio įvykių kvotą (įskaitant bendrinimą, bendrinimo atšaukimą ir atstatymą). Sąrašo / gavimo / statistikos / eksporto / bendrinimų sąrašo / su jumis bendrinamų elementų / webhook sąrašo ir gavimo operacijos neįskaičiuojamos. Apsilankymų / atsisiuntimų / paleidimų registravimas vis tiek įskaičiuojamas.

## Galiniai taškai

| 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` (be 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` (be `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` |
| (pagrindinės sistemos PUT po išdavimo) | `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` ir `auth logout` yra įrenginio autorizacijos srautai naršyklėje. Tai nėra Unkey maršrutai.

## `GET /me`

Prisijungusi paskyra. `{ "userId": "...", "email": "...", "name": "..." }`. El. paštas ir vardas praleidžiami, kai jie nežinomi.

## URL nuorodos kūrimas

```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"}'
```

JSON užklausos turinys priima lygiai vieną iš `url`, `text` arba `storageId`, taip pat neprivalomus laukus `access` (`restricted` numatytasis \| `link` \| `public`), `slug`, `name`, `tags`, `starts`, `expires`, `maxOpenings`, `password`, `domain`, `previewName`, `previewDescription`, `previewImageStorageId`, `sticky`, `forwardParams`, `utm` (tik URL nuorodoms) ir `folder` (+ `folderDomain`), kad nuoroda būtų sukurta aplanke. Sutrumpinta forma sukuria vieną variantą pavadinimu `main`; aukščiausio lygio `password`, `starts`, `expires` ir `maxOpenings` yra nuorodos lygmens apribojimai. Atsakymas: `{ "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }`.

`GET /links` grąžina vieną puslapį, `{ "items": [...], "cursor" }`: `?limit=` yra 1–100 (numatytoji reikšmė 50); perduokite `?cursor=` iš ankstesnio puslapio, kol jis taps `null`. `q` atitinka ištisus žodžius (paskutinį – kaip priešdėlį), rezultatai rikiuojami pagal aktualumą. Elementai yra `{ id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id }` (aplankų eilutės papildomai turi `items`); filtras `kind` papildomai leidžia `folder` ir `group`, filtras `status` papildomai leidžia `mixed`, o `folder=<slug>|root` (+ `folderDomain`) pateikia vieno aplanko arba aukščiausio lygio sąrašą. `GET /links/:id` grąžina visą nuorodą su `access` ir `variants`; turinys (`destinationUrl` / `textContent` / `fileName`) saugomas kiekviename variante.

## Failo įkėlimas

Gaukite įkėlimo URL (`{uploadUrl,storageId}`), išsiųskite baitus PUT užklausa iš pagrindinės sistemos, tada tame pačiame sraute sukurkite nuorodą:

```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}'
```

Mažiems failams vis dar galima naudoti multipart su `POST /links`:

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -F "file=@./deck.pdf" \
  -F "expires=7d" \
  -F "slug=deck"
```

Neprivalomi multipart laukai: `access`, `slug`, `name`, `tags`, `starts` / `startsAt`, `password`, `expires`, `maxOpenings`, `domain`, `previewName`, `previewDescription`, `previewImage`.

## Atnaujinimas, statistika, CSV

`PATCH /links/:id` priima JSON arba multipart. Failo baitus pakeiskite naudodami `storageId` po `POST /uploads` ir PUT užklausos iš pagrindinės sistemos arba multipart lauką `file` (tik vieno varianto nuorodoms). `--status` / `{ "status": "expired" }` atmetamas – naudokite `expires`. `{ "status": "scheduled" }` atmetamas – naudokite `starts`. Neprivalomas `maxOpenings` pristabdo nuorodą po nurodyto atidarymų skaičiaus; `clearMaxOpenings` pašalina limitą. `sticky` (loginė reikšmė) ir `restartSplit` (loginė reikšmė) valdo variantų priskyrimą; `forwardParams` (loginė reikšmė) perduoda lankytojo užklausos eilutę, žr. [Užklausos parametrų perdavimas](#forward-query-parameters). `access` keičia, kas gali ją atidaryti; `resetShareLink: true` išduoda naują bendrinimo URL. Atsakymas: `{ "id", "url", "access", "status", "variantStatuses" }`.

`GET /links/:id/stats?last=24h` grąžina `visits`, `downloads`, `plays`, `visitsInLast`, `countries`, `referrers`, `variants` (kiekvieno varianto sumos), `visitors` ir `crawlers` (`[{ "crawler", "company", "category", "hits", "lastSeen" }]`: robotai ir nuorodų peržiūros, kurie užklausė nuorodą; jie niekada neskaičiuojami kaip apsilankymai; žr. [Robotų žurnalas](https://linkdash.dev/pricing.md)).

`GET /links/export` yra CSV su stulpeliais `slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`, po vieną eilutę kiekvienam variantui (`folder` yra jį turinčio aplanko slug; `access` yra `restricted`, `link` arba `public`). `POST /links/import` priima neapdorotą CSV arba multipart `file`; eilutės grupuojamos pagal slug + domeną (pirmoji eilutė sukuria nuorodą su jos variantu, kitos eilutės prideda variantus; esamų nuorodų laukai atnaujinami, tada variantai atnaujinami arba pridedami pagal pavadinimą). `kind` `folder` eilutės (su `name`) sukuria aplankus, o stulpelis `folder` paskirsto nuorodas, kai visos eilutės jau sukurtos. Tuščias `access` naujas nuorodas padaro ribotos prieigos, o esamas palieka nepakeistas.

`DELETE /links/:id` aplankui priima `?contents=keep` (numatytasis: elementai perkeliami vienu lygiu aukščiau) arba `?contents=delete` (taip pat ištrinami jame esantys elementai ir aplankai).

## Variantai

Kiekviena nuoroda yra vieno ar daugiau **variantų** konteineris: turinys (`url` | `file` | `text`) ir savi apribojimai (`password`, `paused`, `starts`, `expires`, `maxOpenings`), `weight` bei neprivalomos lankytojo sąlygos `when`. Nuorodai priklauso slug, domenas, pavadinimas, žymos, peržiūra, jos pačios apribojimai (kurie turi pirmenybę prieš variantų apribojimus), `sticky` (numatytoji reikšmė `true`) ir `splitVersion` (padidinamas naudojant `restartSplit`). Be `variants` nuoroda turi vieną variantą pavadinimu `main`. Pavadinimai: mažosios raidės, skaitmenys, vidiniai brūkšneliai, 1–40 simbolių, unikalūs nuorodos ribose. Daugiausia 20 variantų vienai nuorodai.

Lankytojas gauna vieną variantą: variantai, kurių `when` atitinka, sudaro rinkinį (jei neatitinka nė vienas – naudojami besąlygiai variantai), tada atliekamas svertinis pasirinkimas (pastovi lankytojo + nuorodos + `splitVersion` maiša, kitu atveju – atsitiktinai). Robotai gauna pirmąjį aktyvų besąlygį variantą. Kai variantų keli, nuorodos `kind` yra `group`. Nuorodos `status` yra nuorodos apribojimų būsena, kai jie nustatyti, kitu atveju – visų variantų bendra būsena, o jei tokios nėra – `mixed`. `variantStatuses` skaičiuoja `{ active, paused, expired, scheduled }`.

Kelių variantų kūrimas vienu metu:

```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"]}}]}'
```

Kiekvienas variantas: `name` (privalomas), vienas iš `url` | `text` | `storageId` (+ `fileName`, `fileType`, `fileSize`), `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when`. Multipart kūrimas palaiko tik sutrumpintą formą.

| Maršrutas | Užklausos turinys | Atsakymas |
| --- | --- | --- |
| `GET /links/:id/variants` | — | variantų masyvas |
| `POST /links/:id/variants` | JSON arba multipart `file`: `name` (privalomas), turinys, `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when` | variantas |
| `PATCH /links/:id/variants/:name` | `name` (pervadinimas), `url`, `text`, `storageId` / `file`, `password`, `clearPassword`, `starts`, `clearStarts`, `expires`, `clearExpires`, `maxOpenings`, `clearMaxOpenings`, `status` (`active` \| `paused`), `weight`, `when`, `clearWhen`, `utm` | variantas |
| `DELETE /links/:id/variants/:name` | — | `{ "id", "variant", "deleted": true }` (paskutinio varianto ištrinti negalima) |

`when` raktai (eilučių masyvai; kiekvienas nustatytas raktas turi atitikti): `countries` (ISO-2), `devices` (`mobile` | `tablet` | `desktop`), `os` (`windows` | `macos` | `android` | `ios` | `linux` | `other`), `browsers` (`edge` | `chrome` | `firefox` | `safari` | `other`), `languages` (priešdėlis), `referrerHosts` (pagrindinio kompiuterio pavadinimo priesaga).

### Užklausos parametrų taisyklės

`when.params` yra iki 10 taisyklių masyvas, taikomas lankytojo užklausos eilutei (`lida.sh/promo?src=newsletter`); turi būti tenkinamos visos taisyklės. Kiekviena taisyklė yra `{ "key", "op", "value" }`, kur `op` yra vienas iš `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` yra `|` arba kableliais atskirtas sąrašas) | `exists` | `missing`. `value` privalomas, išskyrus `exists` / `missing`. Raktai skiria didžiąsias ir mažąsias raides, reikšmės lyginamos tiksliai.

```json
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
```

Parametrų reikšmės tikrinamos atidarymo metu ir niekada nesaugomos analitikoje.

### Užklausos parametrų perdavimas

`forwardParams` (nuorodos loginė reikšmė, numatytoji `false`; nustatoma per `POST /links` ir `PATCH /links/:id`, grąžinama per `GET /links/:id`) prideda visą lankytojo užklausos eilutę prie URL variantų. Lankytojo reikšmės pakeičia išsaugotąsias, įskaitant `utm`. Failų ir teksto variantai šį nustatymą ignoruoja. Tai maršrutizavimas, o ne prieigos kontrolė: parametrus gali pridėti bet kas. Parametrų reikšmės nesaugomos analitikoje.

## Aplankai

Aplankas yra nuoroda, pateikianti į ją įdėtų elementų sąrašą. Modelio aprašymą rasite skiltyje [Aplankai](/lt/folders).

```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_..."
```

| Maršrutas | Užklausos turinys | Atsakymas |
| --- | --- | --- |
| `POST /links` | `{ "kind": "folder", "name" }` ir įprasti nuorodos laukai; be `url`, `text`, `storageId` ar `variants` | sukurtas aplankas |
| `POST /links/:id/move` | `{ "folder": "<slug>" }` arba `{ "folder": null }` aukščiausiam lygiui, neprivalomas `folderDomain` | `{ "id", "folder" }` |
| `POST /links/:id/copy` | — | `{ "id", "url", "access", "kind", "variants", "folder", … }` (ta pati prieiga, naujas bendrinimo URL, be žmonių) |

Perkėlimas ir kopijavimas kiekvienas skaičiuojami kaip vienas įvykis. Nežinomas aplanko slug grąžina `404` (`Folder "<slug>" not found`); slug, kuris nėra aplankas, arba aplanko perkėlimas į save patį ar į žemiau esantį aplanką grąžina `400`. Aplankai gali būti įdėti vienas į kitą ne daugiau kaip 32 lygiais.

## Prieiga ir bendrinimas

Kiekviena nuoroda ir aplankas turi `access`: `restricted` (numatytasis; savininkas ir prisijungę žmonės, su kuriais ji bendrinama, adresu `https://linkdash.dev/s/<token>`), `link` (bet kas, turintis tą URL) arba `public` (bet kas, trumpuoju URL). Nustatykite jį per `POST /links` arba `PATCH /links/:id`. Nuorodoms, skirtoms skelbti viešai, perduokite `"access": "public"`. Kaip veikia aplankai ir peržiūrėtojai, aprašyta skiltyje [Bendrinimas ir prieiga](/lt/sharing).

```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_..."
```

| Maršrutas | Užklausos turinys | Atsakymas |
| --- | --- | --- |
| `POST /links/:id/shares` | `{ "emails": [...] }` (1–50 el. pašto adresų) | `{ "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" }` (viskas, ką bendrinote) |
| `GET /shared` | — | `{ "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }` |
| `DELETE /shared/:id` | — | `{ "_id", "left": true }` (`:id` yra `_id` arba bendrinimo žetonas iš `GET /shared`) |
| `POST /links/:id/reset-link` | — | `{ "id", "access", "url" }` |

`POST /links/:id/shares` priima `"role": "editor"` redaktoriams. Redaktoriai keičia elementus ir mato statistiką bei veiklą, tačiau niekada negali keisti slaptažodžių, slug, domeno, prieigos, bendrinimo, trinti, perkelti ar kopijuoti (`403`); kaip `:id` jie naudoja elemento `_id` arba bendrinimo žetoną, o slaptažodžiu apsaugotas variantas lieka `locked: true`, kol neatliekama `POST /links/:id/unlock` (30 minučių, dešimt neteisingų slaptažodžių per valandą, tada `429`). Išsaugojimas po to, kai išsaugojo kitas asmuo, grąžina `409` tik tada, kai užklausoje siunčiamas `expectedVersion`. Visi bendrinimo maršrutai priima `?domain=`, kai slug kartojasi. `accepted` yra `false`, kol tas el. pašto adresas neturi patvirtintos paskyros; `viaFolder` reiškia, kad prieiga gauta per aukščiau esantį aplanką. Iki 200 žmonių vienam elementui ir iki 100 kvietimų el. laiškų vienai paskyrai per dieną. `GET /shares` ir `GET /shared` grąžina po vieną puslapį: `?limit=` yra 1–100 (numatytoji reikšmė 50); perduokite `?cursor=` iš ankstesnio puslapio, kol `cursor` taps `null`. Bendrinimas, bendrinimo atšaukimas ir atstatymas kiekvienas skaičiuojami kaip vienas įvykis; išėjimas neskaičiuojamas. Prieiga per aukščiau esantį bendrinamą aplanką išlieka ir išėjus.

## Klaidos

| Būsena | Kada |
| --- | --- |
| 400 | Validavimo klaida, trūksta užklausos turinio, sumaišyti kūrimo tipai |
| 401 | Trūksta prieigos rakto (bearer) arba jis neteisingas |
| 404 | Nežinomas slug, domenas arba aplankas |
| 409 | Slug užimtas (`code: "slug_taken"`) |
| 429 | Pasiekta mėnesio įvykių kvota |
| 503 | Šiame diegime API raktai nesukonfigūruoti |

Šiuos galinius taškus rasite skiltyse [webhooks](/lt/webhooks) ir [pasirinktiniai domenai](/lt/domains).
