---
title: HTTP API
description: >-
  REST na https://api.linkdash.dev/v1 s bearer kľúčom z dashboardu. Rovnaké
  operácie ako v CLI a MCP.
sidebar:
  label: HTTP API
  order: 4
---
Základná URL: `https://api.linkdash.dev/v1`

Overenie: `Authorization: Bearer ldash_...` (kľúče vytvoríte v [Dashboard → API kľúče](https://linkdash.dev/dashboard/keys)). Kľúče si nevymýšľajte.

Referencia CLI: [CLI](/sk/cli). MCP: [MCP](/sk/mcp). Ceny / kvóty: [Ceny](/sk/pricing). Discovery (bez overenia): `GET https://api.linkdash.dev/v1`. Čistý markdown: [api.md](https://linkdash.dev/api.md).

Verejné identifikátory sú slugy (`deck`, `k3m9xq`), nie Convex `_id`. Názvy polí v JSON zodpovedajú výstupu CLI na stdout (`id`, `url`, `kind`, …).

## Konvencie

- JSON `Content-Type: application/json`, ak nie je uvedené inak.
- Vytvorenie prijíma presne jedno z `url`, `text` alebo `storageId` po `POST /uploads`, **alebo** pole `variants` (pozri [Varianty](#variants)), **alebo** `"kind": "folder"` s `name` (pozri [Priečinky](#folders)). Vygenerovanie URL na nahratie vracia `{ "uploadUrl", "storageId" }`. Hostiteľ odošle bajty cez PUT na `uploadUrl`. Malé súbory môžu stále použiť multipart `file` na `POST /links`.
- Trvania: `7d`, `24h`, `30m`, `1w` alebo dátum ISO. Polia: `expires` / `expiresAt`, `starts` / `startsAt`.
- Limit otvorení: voliteľné kladné celé číslo `maxOpenings`. Odkaz sa pozastaví po danom počte úspešných otvorení. Ak ho chcete znova sprístupniť, zvýšte `maxOpenings` alebo použite `clearMaxOpenings`. Pre neobmedzený počet `maxOpenings` vynechajte.
- Ak slug existuje na dvoch doménach vlastníka, odovzdajte `?domain=` / JSON `domain`.
- Chyby: `{ "error": "..." }` plus voliteľný `code`. Obsadené slugy `lida.sh` vracajú `409` s `code: "slug_taken"`.
- Prístup: nové odkazy a priečinky sú `restricted`, pokiaľ telo nenastaví `access` (pozri [Prístup a zdieľanie](#access-and-sharing)). `url` v odpovediach je URL na zdieľanie (`https://linkdash.dev/s/<token>`), okrem prípadu, keď je odkaz verejný – vtedy je to krátka URL.
- Zápisy sa započítavajú do mesačnej kvóty udalostí (vrátane zdieľania, zrušenia zdieľania a resetu). List / get / stats / export / zoznam zdieľaní / shared / webhook list/get sa nezapočítavajú. Príjem návštev / stiahnutí / prehratí sa stále započítava.

## Endpointy

| 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` (bez 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` (bez `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 hostiteľa po vygenerovaní URL) | `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` a `auth logout` sú device flow v prehliadači. Nie sú to trasy Unkey.

## `GET /me`

Prihlásený účet. `{ "userId": "...", "email": "...", "name": "..." }`. E-mail a meno sa vynechajú, ak nie sú známe.

## Vytvorenie URL odkazu

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

Telo JSON prijíma presne jedno z `url`, `text` alebo `storageId`, plus voliteľné `access` (`restricted` predvolené \| `link` \| `public`), `slug`, `name`, `tags`, `starts`, `expires`, `maxOpenings`, `password`, `domain`, `previewName`, `previewDescription`, `previewImageStorageId`, `sticky`, `forwardParams`, `utm` (iba URL odkazy) a `folder` (+ `folderDomain`) na vytvorenie v priečinku. Skrátený zápis vytvorí jeden variant s názvom `main`; `password`, `starts`, `expires` a `maxOpenings` na najvyššej úrovni tvoria bránu odkazu. Odpoveď: `{ "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }`.

`GET /links` vracia jednu stránku, `{ "items": [...], "cursor" }`: `?limit=` je 1-100 (predvolene 50); odovzdávajte `?cursor=` z predchádzajúcej stránky, kým nie je `null`. `q` hľadá celé slová (posledné ako prefix), výsledky sú zoradené podľa relevancie. Položky sú `{ id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id }` (riadky priečinkov pridávajú `items`); filter `kind` pridáva `folder` a `group`, filter `status` pridáva `mixed` a `folder=<slug>|root` (+ `folderDomain`) vypíše jeden priečinok alebo najvyššiu úroveň. `GET /links/:id` vracia celý odkaz s `access` a `variants`; obsah (`destinationUrl` / `textContent` / `fileName`) je uložený pri každom variante.

## Nahratie súboru

Vygenerujte URL na nahratie (`{uploadUrl,storageId}`), odošlite bajty cez PUT z hostiteľa a potom v rovnakom postupe vytvorte odkaz:

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

Malé súbory môžu stále použiť multipart na `POST /links`:

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

Voliteľné multipart polia: `access`, `slug`, `name`, `tags`, `starts` / `startsAt`, `password`, `expires`, `maxOpenings`, `domain`, `previewName`, `previewDescription`, `previewImage`.

## Aktualizácia, štatistiky, CSV

`PATCH /links/:id` prijíma JSON alebo multipart. Bajty súboru nahradíte pomocou `storageId` po `POST /uploads` + PUT hostiteľa, alebo multipart poľom `file` (iba odkazy s jedným variantom). `--status` / `{ "status": "expired" }` sa zamietne – použite `expires`. `{ "status": "scheduled" }` sa zamietne – použite `starts`. Voliteľné `maxOpenings` pozastaví odkaz po danom počte otvorení; `clearMaxOpenings` limit odstráni. `sticky` (boolean) a `restartSplit` (boolean) riadia priraďovanie variantov; `forwardParams` (boolean) preposiela query string návštevníka, pozri [Preposielanie query parametrov](#forward-query-parameters). `access` určuje, kto môže odkaz otvoriť; `resetShareLink: true` vydá novú URL na zdieľanie. Odpoveď: `{ "id", "url", "access", "status", "variantStatuses" }`.

`GET /links/:id/stats?last=24h` vracia `visits`, `downloads`, `plays`, `visitsInLast`, `countries`, `referrers`, `variants` (súčty za jednotlivé varianty), `visitors` a `crawlers` (`[{ "crawler", "company", "category", "hits", "lastSeen" }]`: boty a náhľady odkazov, ktoré odkaz načítali, nikdy sa nezapočítavajú ako návštevy; pozri [Záznam crawlerov](https://linkdash.dev/pricing.md)).

`GET /links/export` je CSV so stĺpcami `slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`, jeden riadok na variant (`folder` je slug nadradeného priečinka; `access` je `restricted`, `link` alebo `public`). `POST /links/import` prijíma surové CSV alebo multipart `file`; riadky sa zoskupujú podľa slugu + domény (prvý riadok vytvorí odkaz s jeho variantom, ďalšie riadky pridajú varianty; pri existujúcich odkazoch sa aktualizujú polia a potom sa podľa názvu aktualizujú alebo pridajú varianty). Riadky s `kind` `folder` (s `name`) vytvárajú priečinky a stĺpec `folder` umiestni odkazy až potom, ako existujú všetky riadky. Prázdne `access` nastaví nové odkazy ako obmedzené a existujúce odkazy ponechá bez zmeny.

`DELETE /links/:id` na priečinku prijíma `?contents=keep` (predvolené: položky sa presunú o úroveň vyššie) alebo `?contents=delete` (odstránia sa aj položky a priečinky v ňom).

## Varianty

Každý odkaz je kontajner jedného alebo viacerých **variantov**: obsah (`url` | `file` | `text`) plus vlastná brána (`password`, `paused`, `starts`, `expires`, `maxOpenings`), `weight` a voliteľné podmienky pre návštevníka `when`. Odkazu patrí slug, doména, názov, štítky, náhľad, jeho vlastná brána (ktorá má prednosť pred bránami variantov), `sticky` (predvolene `true`) a `splitVersion` (zvyšuje sa pomocou `restartSplit`). Bez `variants` má odkaz jeden variant s názvom `main`. Názvy: malé písmená, číslice, vnútorné spojovníky, 1–40 znakov, jedinečné v rámci odkazu. Najviac 20 variantov na odkaz.

Návštevník dostane jeden variant: varianty, ktorých `when` vyhovuje, tvoria výberovú množinu (ak nevyhovuje žiadny, použijú sa nepodmienené varianty), potom nasleduje vážený výber (sticky hash návštevníka + odkazu + `splitVersion`, inak náhodne). Crawlery dostanú prvý aktívny nepodmienený variant. `kind` odkazu je `group`, ak má viac variantov. `status` odkazu je stav brány odkazu, ak je nastavená, inak stav spoločný pre všetky varianty, inak `mixed`. `variantStatuses` počíta `{ active, paused, expired, scheduled }`.

Vytvorenie viacerých variantov naraz:

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

Každý variant: `name` (povinné), jedno z `url` | `text` | `storageId` (+ `fileName`, `fileType`, `fileSize`), `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when`. Vytvorenie cez multipart podporuje iba skrátený zápis.

| Trasa | Telo | Odpoveď |
| --- | --- | --- |
| `GET /links/:id/variants` | — | pole variantov |
| `POST /links/:id/variants` | JSON alebo multipart `file`: `name` (povinné), obsah, `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when` | variant |
| `PATCH /links/:id/variants/:name` | `name` (premenovanie), `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 }` (posledný variant nemožno odstrániť) |

Kľúče `when` (polia reťazcov; každý nastavený kľúč musí vyhovovať): `countries` (ISO-2), `devices` (`mobile` | `tablet` | `desktop`), `os` (`windows` | `macos` | `android` | `ios` | `linux` | `other`), `browsers` (`edge` | `chrome` | `firefox` | `safari` | `other`), `languages` (prefix), `referrerHosts` (prípona hostiteľa).

### Pravidlá query parametrov

`when.params` je pole s najviac 10 pravidlami pre query string návštevníka (`lida.sh/promo?src=newsletter`); musia platiť všetky pravidlá. Každé pravidlo má tvar `{ "key", "op", "value" }`, kde `op` je jedno z `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` je zoznam oddelený `|` alebo čiarkou) | `exists` | `missing`. `value` je povinné okrem `exists` / `missing`. Kľúče rozlišujú veľké a malé písmená, hodnoty sa porovnávajú presne.

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

Hodnoty parametrov sa vyhodnocujú pri otvorení a nikdy sa neukladajú do analytiky.

### Preposielanie query parametrov

`forwardParams` (boolean na odkaze, predvolene `false`; dá sa nastaviť v `POST /links` a `PATCH /links/:id`, vracia ho `GET /links/:id`) pripojí celý query string návštevníka k URL variantom. Hodnoty od návštevníka prepíšu uložené hodnoty vrátane `utm`. Súborové a textové varianty ho ignorujú. Ide o smerovanie, nie o riadenie prístupu: parametre môže pridať ktokoľvek. Hodnoty parametrov sa neukladajú do analytiky.

## Priečinky

Priečinok je odkaz, ktorý zobrazuje zoznam položiek, ktoré doň vložíte. Model je opísaný na stránke [Priečinky](/sk/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_..."
```

| Trasa | Telo | Odpoveď |
| --- | --- | --- |
| `POST /links` | `{ "kind": "folder", "name" }` plus bežné polia odkazu; bez `url`, `text`, `storageId` alebo `variants` | vytvorený priečinok |
| `POST /links/:id/move` | `{ "folder": "<slug>" }` alebo `{ "folder": null }` pre najvyššiu úroveň, voliteľné `folderDomain` | `{ "id", "folder" }` |
| `POST /links/:id/copy` | — | `{ "id", "url", "access", "kind", "variants", "folder", … }` (rovnaký prístup, nová URL na zdieľanie, bez ľudí) |

Presun aj kópia sa každý započítavajú ako jedna udalosť. Neznámy slug priečinka vracia `404` (`Folder "<slug>" not found`); slug, ktorý nie je priečinkom, alebo presun priečinka do seba samého či do priečinka pod ním vracia `400`. Priečinky možno vnoriť najviac do hĺbky 32.

## Prístup a zdieľanie

Každý odkaz a priečinok má `access`: `restricted` (predvolené; vlastník a ľudia, s ktorými je zdieľaný, po prihlásení, na `https://linkdash.dev/s/<token>`), `link` (ktokoľvek s touto URL) alebo `public` (ktokoľvek, na krátkej URL). Nastavte ho v `POST /links` alebo `PATCH /links/:id`. Pre odkazy určené na verejné zverejnenie odovzdajte `"access": "public"`. Ako fungujú priečinky a diváci, nájdete na stránke [Zdieľanie a prístup](/sk/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_..."
```

| Trasa | Telo | Odpoveď |
| --- | --- | --- |
| `POST /links/:id/shares` | `{ "emails": [...] }` (1–50 e-mailov) | `{ "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" }` (všetko, čo ste zdieľali) |
| `GET /shared` | — | `{ "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }` |
| `DELETE /shared/:id` | — | `{ "_id", "left": true }` (`:id` je `_id` alebo token zdieľania z `GET /shared`) |
| `POST /links/:id/reset-link` | — | `{ "id", "access", "url" }` |

`POST /links/:id/shares` prijíma `"role": "editor"` pre editorov. Editori môžu meniť položky a vidia štatistiky a aktivitu, ale nikdy nemôžu meniť heslá, slug, doménu, prístup ani zdieľanie a nemôžu odstraňovať, presúvať ani kopírovať (`403`). Ako `:id` používajú `_id` položky alebo token zdieľania a variant chránený heslom zostáva `locked: true`, kým nezavolajú `POST /links/:id/unlock` (30 minút, desať nesprávnych hesiel za hodinu, potom `429`). Uloženie po tom, čo medzitým uložil niekto iný, vráti `409` iba vtedy, keď požiadavka posiela `expectedVersion`. Všetky trasy zdieľania prijímajú `?domain=`, keď sa slug opakuje. `accepted` je `false`, kým daný e-mail nemá overený účet; `viaFolder` znamená, že prístup pochádza z nadradeného priečinka. Najviac 200 ľudí na položku a 100 e-mailov s pozvánkou na účet za deň. `GET /shares` a `GET /shared` vracajú výsledky po stránkach: `?limit=` je 1-100 (predvolene 50); odovzdávajte `?cursor=` z predchádzajúcej stránky, kým `cursor` nie je `null`. Zdieľanie, zrušenie zdieľania a reset sa každé započítavajú ako jedna udalosť; opustenie nie. Prístup cez zdieľaný nadradený priečinok zostáva zachovaný aj po opustení.

## Chyby

| Stav | Kedy |
| --- | --- |
| 400 | Validácia, chýbajúce telo, kombinované typy vytvorenia |
| 401 | Chýbajúci alebo neplatný bearer kľúč |
| 404 | Neznámy slug, doména alebo priečinok |
| 409 | Slug je obsadený (`code: "slug_taken"`) |
| 429 | Dosiahnutá mesačná kvóta udalostí |
| 503 | API kľúče nie sú v tomto nasadení nakonfigurované |

Tieto endpointy opisujú stránky [webhooky](/sk/webhooks) a [vlastné domény](/sk/domains).
