---
title: HTTP API
description: >-
  REST aadressil https://api.linkdash.dev/v1, autentimiseks armatuurlaualt
  saadud bearer-võti. Toimingud on samad mis CLI-s ja MCP-s.
sidebar:
  label: HTTP API
  order: 4
---
Baas-URL: `https://api.linkdash.dev/v1`

Autentimine: `Authorization: Bearer ldash_...` (võtmed saad luua lehel [Armatuurlaud → API-võtmed](https://linkdash.dev/dashboard/keys)). Ära mõtle võtmeid ise välja.

CLI viide: [CLI](/et/cli). MCP: [MCP](/et/mcp). Hinnad / kvoodid: [Hinnad](/et/pricing). Avastamine (autentimiseta): `GET https://api.linkdash.dev/v1`. Puhas markdown: [api.md](https://linkdash.dev/api.md).

Avalikud ID-d on slugid (`deck`, `k3m9xq`), mitte Convexi `_id`. JSON-väljade nimed on samad mis CLI stdout'is (`id`, `url`, `kind`, …).

## Kokkulepped

- Kasutusel on JSON `Content-Type: application/json`, kui pole öeldud teisiti.
- Loomisel anna täpselt üks järgmistest: `url`, `text` või `storageId` (pärast `POST /uploads`), **või** massiiv `variants` (vt [Variandid](#variants)), **või** `"kind": "folder"` koos väljaga `name` (vt [Kaustad](#folders)). Üleslaadimis-URL-i loomine tagastab `{ "uploadUrl", "storageId" }`. Host saadab baidid PUT-päringuga aadressile `uploadUrl`. Väikeste failide puhul võid endiselt kasutada multipart-välja `file` päringus `POST /links`.
- Kestused: `7d`, `24h`, `30m`, `1w` või ISO-kuupäev. Väljad: `expires` / `expiresAt`, `starts` / `startsAt`.
- Avamiste piirang: valikuline positiivne täisarv `maxOpenings`. Kui link on nii mitu korda edukalt avatud, see peatub. Et link jälle töötaks, tõsta `maxOpenings` väärtust või kasuta `clearMaxOpenings`. Kui piirangut pole vaja, jäta `maxOpenings` ära.
- Kui sama slug on olemas omaniku kahel domeenil, anna kaasa `?domain=` / JSON-väli `domain`.
- Vead: `{ "error": "..." }` ja valikuline `code`. Juba võetud `lida.sh` slugi korral tuleb vastuseks `409` koos `code: "slug_taken"`.
- Ligipääs: uued lingid ja kaustad on `restricted`, kui keha ei määra välja `access` (vt [Ligipääs ja jagamine](#access-and-sharing)). Vastustes on `url` jagamis-URL (`https://linkdash.dev/s/<token>`). Avaliku lingi puhul on see lühi-URL.
- Kirjutamistoimingud lähevad kuise sündmuste kvoodi hulka (ka jagamine, jagamise lõpetamine ja lähtestamine). List / get / stats / export / shares list / shared / webhook list/get kvooti ei kuluta. Külastuste / allalaadimiste / esituste registreerimine läheb endiselt arvesse.

## Otspunktid

| 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` (ilma id-ta) | `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` (ilma `id`-ta) |
| `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` |
| (hosti PUT pärast URL-i loomist) | `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` ja `auth logout` on brauseripõhised seadmevood. Need ei ole Unkey marsruudid.

## `GET /me`

Sisselogitud konto. `{ "userId": "...", "email": "...", "name": "..." }`. Kui e-post või nimi pole teada, jäetakse need vastusest välja.

## URL-lingi loomine

```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-kehas peab olema täpselt üks väljadest `url`, `text` või `storageId`. Lisaks saad anda valikulised väljad `access` (vaikimisi `restricted` \| `link` \| `public`), `slug`, `name`, `tags`, `starts`, `expires`, `maxOpenings`, `password`, `domain`, `previewName`, `previewDescription`, `previewImageStorageId`, `sticky`, `forwardParams`, `utm` (ainult URL-linkidel) ning `folder` (+ `folderDomain`), kui tahad lingi kohe kausta luua. Lühivorm loob ühe variandi nimega `main`. Ülemise taseme `password`, `starts`, `expires` ja `maxOpenings` moodustavad lingi värava. Vastus: `{ "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }`.

`GET /links` tagastab ühe lehekülje kujul `{ "items": [...], "cursor" }`. `?limit=` on vahemikus 1-100 (vaikimisi 50). Anna eelmiselt leheküljelt saadud `?cursor=` kaasa, kuni see on `null`. `q` otsib terveid sõnu (viimast sõna prefiksina) ja järjestab tulemused asjakohasuse järgi. Elemendid on kujul `{ id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id }` (kaustaridadel on lisaks `items`). `kind`-filtril on lisaks väärtused `folder` ja `group`, `status`-filtril lisaks `mixed`. `folder=<slug>|root` (+ `folderDomain`) näitab ühe kausta sisu või ülemist taset. `GET /links/:id` tagastab kogu lingi koos väljadega `access` ja `variants`. Sisu (`destinationUrl` / `textContent` / `fileName`) on iga variandi juures eraldi.

## Faili üleslaadimine

Loo üleslaadimis-URL (`{uploadUrl,storageId}`), saada baidid hostist PUT-päringuga ja loo siis samas voos link:

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

Väikeste failide puhul võid endiselt kasutada multiparti päringus `POST /links`:

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

Valikulised multipart-väljad: `access`, `slug`, `name`, `tags`, `starts` / `startsAt`, `password`, `expires`, `maxOpenings`, `domain`, `previewName`, `previewDescription`, `previewImage`.

## Uuendamine, statistika, CSV

`PATCH /links/:id` võtab vastu JSON-i või multiparti. Faili baitide asendamiseks kasuta `storageId`-d (pärast `POST /uploads` ja hosti PUT-i) või multipart-välja `file` (ainult ühe variandiga linkidel). `--status` / `{ "status": "expired" }` lükatakse tagasi, kasuta selle asemel `expires`. Ka `{ "status": "scheduled" }` lükatakse tagasi, kasuta selle asemel `starts`. Valikuline `maxOpenings` peatab lingi pärast nii mitut avamist, `clearMaxOpenings` eemaldab piirangu. `sticky` (boolean) ja `restartSplit` (boolean) määravad, kuidas külastajad variantide vahel jaotatakse. `forwardParams` (boolean) edastab külastaja päringustringi, vt [Päringuparameetrite edastamine](#forward-query-parameters). `access` määrab, kes saab linki avada. `resetShareLink: true` annab lingile uue jagamis-URL-i. Vastus: `{ "id", "url", "access", "status", "variantStatuses" }`.

`GET /links/:id/stats?last=24h` tagastab väljad `visits`, `downloads`, `plays`, `visitsInLast`, `countries`, `referrers`, `variants` (iga variandi kogusummad), `visitors` ja `crawlers` (`[{ "crawler", "company", "category", "hits", "lastSeen" }]`). `crawlers` näitab botte ja lingieelvaateid, mis on linki laadinud. Neid ei loeta kunagi külastusteks, vt [Indekseerijate logi](https://linkdash.dev/pricing.md).

`GET /links/export` tagastab CSV veergudega `slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`, iga variant eraldi real. `folder` on kausta slug, kus link asub. `access` on `restricted`, `link` või `public`. `POST /links/import` võtab vastu toore CSV või multipart-välja `file`. Read rühmitatakse slugi ja domeeni järgi: esimene rida loob lingi koos variandiga ja järgmised read lisavad variante. Olemasolevate linkide puhul uuendatakse välju ja seejärel uuendatakse või lisatakse variante nime järgi. Read, kus `kind` on `folder` (ja `name` on olemas), loovad kaustad. Veeru `folder` järgi paigutatakse lingid kaustadesse alles siis, kui kõik read on loodud. Kui `access` on tühi, saavad uued lingid väärtuse restricted ja olemasolevad lingid jäävad muutmata.

Kausta kustutamisel saad `DELETE /links/:id` päringule anda `?contents=keep` (vaikimisi: elemendid liiguvad taseme võrra üles) või `?contents=delete` (kustutatakse ka kaustas olevad elemendid ja alamkaustad).

## Variandid

Iga link sisaldab ühte või mitut **varianti**. Variandil on sisu (`url` | `file` | `text`), oma värav (`password`, `paused`, `starts`, `expires`, `maxOpenings`), kaal `weight` ja valikulised külastajatingimused `when`. Lingile endale kuuluvad slug, domeen, nimi, sildid, eelvaade, lingi värav (mis on variantide väravatest tähtsam), `sticky` (vaikimisi `true`) ja `splitVersion` (`restartSplit` suurendab seda). Kui `variants` puudub, on lingil üks variant nimega `main`. Nimes võivad olla väiketähed, numbrid ja sidekriipsud (mitte alguses ega lõpus), pikkus 1–40 märki ning nimi peab lingi piires olema unikaalne. Ühel lingil saab olla kuni 20 varianti.

Iga külastaja saab ühe variandi. Kõigepealt kogutakse variandid, mille `when` sobib. Kui ükski ei sobi, võetakse tingimusteta variandid. Nende seast valitakse kaalu järgi: kui `sticky` on sees, määrab valiku külastaja, lingi ja `splitVersion`-i põhjal arvutatud räsi, muidu on valik juhuslik. Indekseerijad saavad esimese aktiivse tingimusteta variandi. Kui variante on mitu, on lingi `kind` väärtus `group`. Lingi `status` on lingi värava staatus, kui värav on määratud. Muidu on see kõigi variantide ühine staatus ja kui see erineb, siis `mixed`. `variantStatuses` loendab `{ active, paused, expired, scheduled }`.

Loo mitu varianti korraga:

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

Iga variandi väljad: `name` (kohustuslik), üks väljadest `url` | `text` | `storageId` (+ `fileName`, `fileType`, `fileSize`), `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when`. Multipart-loomine toetab ainult lühivormi.

| Marsruut | Keha | Vastus |
| --- | --- | --- |
| `GET /links/:id/variants` | — | variantide massiiv |
| `POST /links/:id/variants` | JSON või multipart `file`: `name` (kohustuslik), sisu, `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when` | variant |
| `PATCH /links/:id/variants/:name` | `name` (ümbernimetamine), `url`, `text`, `storageId` / `file`, `password`, `clearPassword`, `starts`, `clearStarts`, `expires`, `clearExpires`, `maxOpenings`, `clearMaxOpenings`, `status` (`active` \| `paused`), `weight`, `when`, `clearWhen`, `utm` | variant |
| `DELETE /links/:id/variants/:name` | — | `{ "id", "variant", "deleted": true }` (viimast varianti ei saa kustutada) |

`when` võtmed (väärtused on stringide massiivid ja iga määratud võti peab sobima): `countries` (ISO-2), `devices` (`mobile` | `tablet` | `desktop`), `os` (`windows` | `macos` | `android` | `ios` | `linux` | `other`), `browsers` (`edge` | `chrome` | `firefox` | `safari` | `other`), `languages` (prefiks), `referrerHosts` (hosti sufiks).

### Päringuparameetrite reeglid

`when.params` on massiiv kuni 10 reegliga, mis kontrollivad külastaja päringustringi (`lida.sh/promo?src=newsletter`). Kõik reeglid peavad kehtima. Iga reegel on kujul `{ "key", "op", "value" }` ja `op` on üks järgmistest: `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` on `|`-ga või komaga eraldatud loend) | `exists` | `missing`. `value` on kohustuslik, välja arvatud `exists` / `missing` puhul. Võtmed on tõstutundlikud ja väärtused peavad täpselt kattuma.

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

Parameetrite väärtusi kontrollitakse lingi avamise hetkel ja neid ei salvestata kunagi analüütikasse.

### Päringuparameetrite edastamine

`forwardParams` on lingi boolean-väli, vaikimisi `false`. Saad selle määrata päringutes `POST /links` ja `PATCH /links/:id` ning `GET /links/:id` tagastab selle. Kui see on sees, lisatakse URL-variantidele kogu külastaja päringustring. Külastaja väärtused kirjutavad salvestatud väärtused üle, ka `utm`. Faili- ja tekstivariandid seda ei arvesta. See on suunamine, mitte ligipääsukontroll: parameetreid saab lisada igaüks. Parameetrite väärtusi analüütikasse ei salvestata.

## Kaustad

Kaust on link, mis näitab sinna pandud elemente. Mudeli kohta loe lähemalt lehelt [Kaustad](/et/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_..."
```

| Marsruut | Keha | Vastus |
| --- | --- | --- |
| `POST /links` | `{ "kind": "folder", "name" }` ja tavalised lingiväljad, aga ilma väljadeta `url`, `text`, `storageId` ja `variants` | loodud kaust |
| `POST /links/:id/move` | `{ "folder": "<slug>" }` või ülemise taseme jaoks `{ "folder": null }`, valikuline `folderDomain` | `{ "id", "folder" }` |
| `POST /links/:id/copy` | — | `{ "id", "url", "access", "kind", "variants", "folder", … }` (sama ligipääs, uus jagamis-URL, inimesi ei kopeerita) |

Liigutamine ja kopeerimine lähevad kumbki arvesse ühe sündmusena. Tundmatu kausta slugi korral tuleb vastuseks `404` (`Folder "<slug>" not found`). Kui slug ei kuulu kaustale või proovid kausta liigutada iseendasse või oma alamkausta, tuleb vastuseks `400`. Kaustu saab pesastada kuni 32 taseme sügavuseni.

## Ligipääs ja jagamine

Igal lingil ja kaustal on väli `access`. `restricted` (vaikimisi) tähendab, et avada saavad omanik ja inimesed, kellega link on jagatud. Nad peavad olema sisse logitud ja link asub aadressil `https://linkdash.dev/s/<token>`. `link` tähendab, et avada saab igaüks, kellel see URL on. `public` tähendab, et avada saab igaüks lühi-URL-i kaudu. Määra ligipääs päringus `POST /links` või `PATCH /links/:id`. Kui link on mõeldud avalikult postitamiseks, anna `"access": "public"`. Kaustade ja vaatajate kohta loe lähemalt lehelt [Jagamine ja ligipääs](/et/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_..."
```

| Marsruut | Keha | Vastus |
| --- | --- | --- |
| `POST /links/:id/shares` | `{ "emails": [...] }` (1–50 e-posti aadressi) | `{ "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" }` (kõik, mida oled jaganud) |
| `GET /shared` | — | `{ "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }` |
| `DELETE /shared/:id` | — | `{ "_id", "left": true }` (`:id` on `_id` või jagamistoken vastusest `GET /shared`) |
| `POST /links/:id/reset-link` | — | `{ "id", "access", "url" }` |

Toimetaja lisamiseks anna päringule `POST /links/:id/shares` väli `"role": "editor"`. Toimetajad saavad elemente muuta ning näevad statistikat ja tegevuslogi. Paroole, slugi, domeeni, ligipääsu ega jagamist nad muuta ei saa, samuti ei saa nad kustutada, liigutada ega kopeerida (`403`). Toimetaja kasutab `:id`-na elemendi `_id`-d või jagamistokenit. Parooliga kaitstud variant jääb olekusse `locked: true`, kuni see avatakse päringuga `POST /links/:id/unlock`. Avamine kehtib 30 minutit ja tunnis on lubatud kümme valet parooli, pärast seda tuleb `429`. Kui keegi teine on vahepeal salvestanud, saad salvestamisel `409`, aga ainult siis, kui päring saadab `expectedVersion`. Kõik jagamismarsruudid võtavad vastu `?domain=`, kui sama slug esineb mitmel domeenil. `accepted` on `false`, kuni sellel e-posti aadressil on kinnitatud konto. `viaFolder` tähendab, et ligipääs tuleb ülemisest kaustast. Ühe elemendiga saab jagada kuni 200 inimest ja üks konto saab päevas saata kuni 100 kutsekirja. `GET /shares` ja `GET /shared` tagastavad tulemused lehekülgede kaupa. `?limit=` on vahemikus 1-100 (vaikimisi 50). Anna eelmiselt leheküljelt saadud `?cursor=` kaasa, kuni `cursor` on `null`. Jagamine, jagamise lõpetamine ja lähtestamine lähevad igaüks arvesse ühe sündmusena, lahkumine mitte. Kui ligipääs tuleb jagatud ülemise kausta kaudu, jääb see pärast lahkumist alles.

## Vead

| Olek | Millal |
| --- | --- |
| 400 | Valideerimisviga, keha puudub või loomisel on segatud eri tüüpe |
| 401 | Bearer-võti puudub või on kehtetu |
| 404 | Tundmatu slug, domeen või kaust |
| 409 | Slug on juba võetud (`code: "slug_taken"`) |
| 429 | Kuine sündmuste kvoot on täis |
| 503 | Selles juurutuses pole API-võtmeid seadistatud |

Nende otspunktide kohta loe lähemalt lehtedelt [webhookid](/et/webhooks) ja [kohandatud domeenid](/et/domains).
