---
title: HTTP API
description: >-
  REST na https://api.linkdash.dev/v1 s klíčem bearer z dashboardu. Stejné
  operace jako v CLI a MCP.
sidebar:
  label: HTTP API
  order: 4
---
Základní URL: `https://api.linkdash.dev/v1`

Ověření: `Authorization: Bearer ldash_...` (klíče vytvoříte v [Dashboard → API klíče](https://linkdash.dev/dashboard/keys)). Klíče si nevymýšlejte.

Reference CLI: [CLI](/cs/cli). MCP: [MCP](/cs/mcp). Ceny / kvóty: [Ceny](/cs/pricing). Discovery (bez ověření): `GET https://api.linkdash.dev/v1`. Čistý markdown: [api.md](https://linkdash.dev/api.md).

Veřejná id jsou slugy (`deck`, `k3m9xq`), nikoli Convex `_id`. Názvy polí JSON odpovídají výstupu CLI na stdout (`id`, `url`, `kind`, …).

## Konvence

- JSON `Content-Type: application/json`, pokud není uvedeno jinak.
- Vytvoření přijímá právě jedno z `url`, `text` nebo `storageId` (po `POST /uploads`), **nebo** pole `variants` (viz [Varianty](#variants)), **nebo** `"kind": "folder"` s `name` (viz [Složky](#folders)). Vygenerování vrací `{ "uploadUrl", "storageId" }`. Hostitel nahraje bajty metodou PUT na `uploadUrl`. Malé soubory mohou stále použít multipart pole `file` v `POST /links`.
- Doby trvání: `7d`, `24h`, `30m`, `1w` nebo datum ve formátu ISO. Pole: `expires` / `expiresAt`, `starts` / `startsAt`.
- Limit otevření: volitelné kladné celé číslo `maxOpenings`. Odkaz se po daném počtu úspěšných otevření pozastaví. Chcete-li jej znovu zpřístupnit, zvyšte `maxOpenings` nebo použijte `clearMaxOpenings`. Pro neomezený počet `maxOpenings` vynechte.
- Pokud slug existuje na dvou doménách vlastníka, předejte `?domain=` / JSON `domain`.
- Chyby: `{ "error": "..." }` a volitelně `code`. Obsazené slugy `lida.sh` vracejí `409` s `code: "slug_taken"`.
- Přístup: nové odkazy a složky jsou `restricted`, pokud tělo nenastaví `access` (viz [Přístup a sdílení](#access-and-sharing)). `url` v odpovědích je URL pro sdílení (`https://linkdash.dev/s/<token>`), pokud odkaz není veřejný; u veřejného odkazu je to krátká URL.
- Zápisy se započítávají do měsíční kvóty událostí (včetně sdílení, zrušení sdílení a resetu). List / get / stats / export / výpis sdílení / shared / webhook list/get se nezapočítávají. Příjem návštěv / stažení / přehrání se stále započítává.

## 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 z hostitele po vygenerování) | `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` jsou toky přihlášení zařízení přes prohlížeč. Nejsou to routy Unkey.

## `GET /me`

Přihlášený účet. `{ "userId": "...", "email": "...", "name": "..." }`. E-mail a jméno se vynechávají, pokud nejsou známy.

## Vytvoření odkazu na 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"}'
```

Tělo JSON přijímá právě jedno z `url`, `text` nebo `storageId` a dále volitelně `access` (výchozí `restricted` \| `link` \| `public`), `slug`, `name`, `tags`, `starts`, `expires`, `maxOpenings`, `password`, `domain`, `previewName`, `previewDescription`, `previewImageStorageId`, `sticky`, `forwardParams`, `utm` (pouze odkazy na URL) a `folder` (+ `folderDomain`) pro vytvoření uvnitř složky. Zkrácený zápis vytvoří jednu variantu s názvem `main`; `password`, `starts`, `expires` a `maxOpenings` na nejvyšší úrovni tvoří bránu odkazu. Odpověď: `{ "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }`.

`GET /links` vrací jednu stránku, `{ "items": [...], "cursor" }`: `?limit=` je 1–100 (výchozí 50); předávejte `?cursor=` z předchozí stránky, dokud nebude `null`. `q` hledá celá slova (poslední jako prefix), seřazená podle relevance. Položky mají tvar `{ id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id }` (řádky složek navíc obsahují `items`); filtr `kind` přidává hodnoty `folder` a `group`, filtr `status` přidává `mixed` a `folder=<slug>|root` (+ `folderDomain`) vypíše jednu složku nebo nejvyšší úroveň. `GET /links/:id` vrací celý odkaz včetně `access` a `variants`; obsah (`destinationUrl` / `textContent` / `fileName`) je uložen u každé varianty.

## Nahrání souboru

Vygenerujte URL pro nahrání (`{uploadUrl,storageId}`), nahrajte bajty z hostitele metodou PUT a poté ve stejném toku vytvořte 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é soubory mohou stále používat multipart v `POST /links`:

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

Volitelná pole multipart: `access`, `slug`, `name`, `tags`, `starts` / `startsAt`, `password`, `expires`, `maxOpenings`, `domain`, `previewName`, `previewDescription`, `previewImage`.

## Aktualizace, statistiky, CSV

`PATCH /links/:id` přijímá JSON nebo multipart. Bajty souboru nahradíte pomocí `storageId` po `POST /uploads` + PUT z hostitele, nebo multipart polem `file` (pouze u odkazů s jednou variantou). `--status` / `{ "status": "expired" }` se odmítá – použijte `expires`. `{ "status": "scheduled" }` se odmítá – použijte `starts`. Volitelné `maxOpenings` pozastaví odkaz po daném počtu otevření; `clearMaxOpenings` limit odstraní. `sticky` (boolean) a `restartSplit` (boolean) řídí přiřazování variant; `forwardParams` (boolean) přeposílá query string návštěvníka, viz [Přeposílání parametrů dotazu](#forward-query-parameters). `access` určuje, kdo může odkaz otevřít; `resetShareLink: true` vydá novou URL pro sdílení. Odpověď: `{ "id", "url", "access", "status", "variantStatuses" }`.

`GET /links/:id/stats?last=24h` vrací `visits`, `downloads`, `plays`, `visitsInLast`, `countries`, `referrers`, `variants` (součty za jednotlivé varianty), `visitors` a `crawlers` (`[{ "crawler", "company", "category", "hits", "lastSeen" }]`: boti a náhledy odkazů, které odkaz načetly; nikdy se nezapočítávají jako návštěvy; viz [Protokol crawlerů](https://linkdash.dev/pricing.md)).

`GET /links/export` vrací CSV se sloupci `slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`, jeden řádek na variantu (`folder` je slug nadřazené složky; `access` je `restricted`, `link` nebo `public`). `POST /links/import` přijímá surové CSV nebo multipart `file`; řádky se seskupují podle slugu + domény (první řádek vytvoří odkaz s jeho variantou, další řádky přidávají varianty; u existujících odkazů se aktualizují pole a poté se podle názvu aktualizují nebo přidají varianty). Řádky s `kind` `folder` (s `name`) vytvářejí složky a sloupec `folder` umístí odkazy až poté, co existují všechny řádky. Prázdné `access` nastaví nové odkazy jako omezené a existující odkazy ponechá beze změny.

`DELETE /links/:id` u složky přijímá `?contents=keep` (výchozí: položky se přesunou o úroveň výš) nebo `?contents=delete` (smažou se i položky a složky uvnitř).

## Varianty

Každý odkaz je kontejnerem jedné či více **variant**: obsah (`url` | `file` | `text`) plus vlastní brána (`password`, `paused`, `starts`, `expires`, `maxOpenings`), `weight` a volitelné podmínky návštěvníka `when`. K odkazu patří slug, doména, název, štítky, náhled, vlastní brána (která má přednost před branami variant), `sticky` (výchozí `true`) a `splitVersion` (zvyšuje se pomocí `restartSplit`). Bez `variants` má odkaz jednu variantu s názvem `main`. Názvy: malá písmena, číslice, vnitřní pomlčky, 1–40 znaků, jedinečné v rámci odkazu. Nejvýše 20 variant na odkaz.

Návštěvník dostane jednu variantu: varianty, jejichž `when` odpovídá, tvoří fond (pokud žádná neodpovídá, tvoří jej varianty bez podmínek), poté následuje vážený výběr (sticky hash návštěvníka + odkazu + `splitVersion`, jinak náhodně). Crawleři dostanou první aktivní variantu bez podmínek. Odkaz s více variantami má `kind` `group`. `status` odkazu je stav brány odkazu, je-li nastavena, jinak stav, který sdílejí všechny varianty, jinak `mixed`. `variantStatuses` počítá `{ active, paused, expired, scheduled }`.

Vytvoření několika variant najednou:

```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á varianta: `name` (povinné), jedno z `url` | `text` | `storageId` (+ `fileName`, `fileType`, `fileSize`), `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when`. Vytvoření přes multipart podporuje pouze zkrácený zápis.

| Routa | Tělo | Odpověď |
| --- | --- | --- |
| `GET /links/:id/variants` | — | pole variant |
| `POST /links/:id/variants` | JSON nebo multipart `file`: `name` (povinné), obsah, `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when` | varianta |
| `PATCH /links/:id/variants/:name` | `name` (přejmenování), `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 }` (poslední variantu nelze smazat) |

Klíče `when` (pole řetězců; každý nastavený klíč musí odpovídat): `countries` (ISO-2), `devices` (`mobile` | `tablet` | `desktop`), `os` (`windows` | `macos` | `android` | `ios` | `linux` | `other`), `browsers` (`edge` | `chrome` | `firefox` | `safari` | `other`), `languages` (prefix), `referrerHosts` (přípona hostitele).

### Pravidla pro parametry dotazu

`when.params` je pole až 10 pravidel pro query string návštěvníka (`lida.sh/promo?src=newsletter`); platit musí všechna pravidla. Každé pravidlo má tvar `{ "key", "op", "value" }`, kde `op` je jedno z `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` je seznam oddělený znakem `|` nebo čárkami) | `exists` | `missing`. `value` je povinné kromě `exists` / `missing`. Klíče rozlišují velká a malá písmena, hodnoty se porovnávají přesně.

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

Hodnoty parametrů se vyhodnocují v okamžiku otevření a nikdy se neukládají do analytiky.

### Přeposílání parametrů dotazu

`forwardParams` (boolean na odkazu, výchozí `false`; lze nastavit v `POST /links` a `PATCH /links/:id`, vrací jej `GET /links/:id`) připojí celý query string návštěvníka k variantám s URL. Hodnoty od návštěvníka přepisují uložené hodnoty, včetně `utm`. Varianty se souborem a textem jej ignorují. Jde o směrování, nikoli o řízení přístupu: parametry může přidat kdokoli. Hodnoty parametrů se neukládají do analytiky.

## Složky

Složka je odkaz, který vypisuje položky, jež do ní vložíte. Model popisuje stránka [Složky](/cs/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_..."
```

| Routa | Tělo | Odpověď |
| --- | --- | --- |
| `POST /links` | `{ "kind": "folder", "name" }` a běžná pole odkazu; bez `url`, `text`, `storageId` nebo `variants` | vytvořená složka |
| `POST /links/:id/move` | `{ "folder": "<slug>" }` nebo `{ "folder": null }` pro nejvyšší úroveň, volitelně `folderDomain` | `{ "id", "folder" }` |
| `POST /links/:id/copy` | — | `{ "id", "url", "access", "kind", "variants", "folder", … }` (stejný přístup, nová URL pro sdílení, bez osob) |

Přesun i kopírování se počítají každé jako jedna událost. Neznámý slug složky vrací `404` (`Folder "<slug>" not found`); slug, který není složkou, nebo přesun složky do sebe sama či do složky pod ní vrací `400`. Složky lze vnořit nejvýše do hloubky 32.

## Přístup a sdílení

Každý odkaz a každá složka má `access`: `restricted` (výchozí; vlastník a lidé, se kterými je sdílen, po přihlášení, na `https://linkdash.dev/s/<token>`), `link` (kdokoli s touto URL) nebo `public` (kdokoli, na krátké URL). Nastavíte jej v `POST /links` nebo `PATCH /links/:id`. U odkazů určených ke zveřejnění předejte `"access": "public"`. Jak fungují složky a diváci, popisuje stránka [Sdílení a přístup](/cs/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_..."
```

| Routa | Tělo | Odpověď |
| --- | --- | --- |
| `POST /links/:id/shares` | `{ "emails": [...] }` (1–50 e-mailů) | `{ "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še, co jste sdíleli) |
| `GET /shared` | — | `{ "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }` |
| `DELETE /shared/:id` | — | `{ "_id", "left": true }` (`:id` je `_id` nebo token sdílení z `GET /shared`) |
| `POST /links/:id/reset-link` | — | `{ "id", "access", "url" }` |

`POST /links/:id/shares` přijímá `"role": "editor"` pro editory. Editoři mohou měnit položky a vidí statistiky a aktivitu, ale nikdy nemají přístup k heslům, slugu, doméně, přístupu, sdílení, mazání, přesunu ani kopírování (`403`); jako `:id` používají `_id` položky nebo token sdílení a varianta chráněná heslem zůstává `locked: true`, dokud nezavolají `POST /links/:id/unlock` (30 minut, deset chybných hesel za hodinu, poté `429`). Uložení poté, co uložil někdo jiný, vrací `409` pouze tehdy, když požadavek posílá `expectedVersion`. Všechny routy sdílení přijímají `?domain=`, pokud se slug opakuje. `accepted` je `false`, dokud daný e-mail nemá ověřený účet; `viaFolder` znamená, že přístup pochází z nadřazené složky. Nejvýše 200 osob na položku a 100 e-mailových pozvánek na účet za den. `GET /shares` a `GET /shared` vracejí výsledky po stránkách: `?limit=` je 1–100 (výchozí 50); předávejte `?cursor=` z předchozí stránky, dokud `cursor` nebude `null`. Sdílení, zrušení sdílení a reset se počítají každé jako jedna událost; opuštění nikoli. Přístup přes sdílenou nadřazenou složku zůstává i po opuštění.

## Chyby

| Stav | Kdy |
| --- | --- |
| 400 | Chyba validace, chybějící tělo, smíšené druhy vytvoření |
| 401 | Chybějící nebo neplatný klíč bearer |
| 404 | Neznámý slug, doména nebo složka |
| 409 | Slug je obsazen (`code: "slug_taken"`) |
| 429 | Dosažena měsíční kvóta událostí |
| 503 | API klíče nejsou v tomto nasazení nakonfigurovány |

Endpointy pro [webhooky](/cs/webhooks) a [vlastní domény](/cs/domains) najdete na jejich stránkách.
