---
title: HTTP API
description: >-
  REST pod https://api.linkdash.dev/v1 z kluczem bearer z dashboardu. Te same
  operacje co w CLI i MCP.
sidebar:
  label: HTTP API
  order: 4
---
Bazowy URL: `https://api.linkdash.dev/v1`

Uwierzytelnianie: `Authorization: Bearer ldash_...` (klucze utworzysz w [Panel → Klucze API](https://linkdash.dev/dashboard/keys)). Nie wymyślaj kluczy.

Dokumentacja CLI: [CLI](/pl/cli). MCP: [MCP](/pl/mcp). Cennik / limity: [Cennik](/pl/pricing). Discovery (bez uwierzytelniania): `GET https://api.linkdash.dev/v1`. Czysty markdown: [api.md](https://linkdash.dev/api.md).

Publiczne identyfikatory to slugi (`deck`, `k3m9xq`), a nie `_id` z Convex. Nazwy pól JSON są takie same jak w stdout CLI (`id`, `url`, `kind`, …).

## Konwencje

- JSON z `Content-Type: application/json`, chyba że zaznaczono inaczej.
- Tworzenie przyjmuje dokładnie jedno z: `url`, `text` lub `storageId` (po `POST /uploads`), **albo** tablicę `variants` (zobacz [Warianty](#variants)), **albo** `"kind": "folder"` z `name` (zobacz [Foldery](#folders)). Wygenerowanie URL-a do uploadu zwraca `{ "uploadUrl", "storageId" }`. Host wysyła bajty PUT-em na `uploadUrl`. Małe pliki nadal mogą używać multipart `file` w `POST /links`.
- Czasy trwania: `7d`, `24h`, `30m`, `1w` albo data ISO. Pola: `expires` / `expiresAt`, `starts` / `startsAt`.
- Limit otwarć: opcjonalna dodatnia liczba całkowita `maxOpenings`. Link zostaje wstrzymany po tylu udanych otwarciach. Zwiększ `maxOpenings` albo użyj `clearMaxOpenings`, żeby znów go serwować. Pomiń `maxOpenings`, jeśli nie chcesz limitu.
- Jeśli slug istnieje w dwóch domenach właściciela, przekaż `?domain=` / pole JSON `domain`.
- Błędy: `{ "error": "..." }` plus opcjonalny `code`. Zajęte slugi `lida.sh` zwracają `409` z `code: "slug_taken"`.
- Dostęp: nowe linki i foldery są `restricted`, chyba że body ustawia `access` (zobacz [Dostęp i udostępnianie](#access-and-sharing)). `url` w odpowiedziach to URL udostępniania (`https://linkdash.dev/s/<token>`), chyba że link jest publiczny — wtedy to krótki URL.
- Zapisy wliczają się do miesięcznego limitu zdarzeń (łącznie z share, unshare i reset). List / get / stats / export / lista udostępnień / shared / webhook list/get się nie wliczają. Rejestrowanie wizyt / pobrań / odtworzeń nadal się wlicza.

## 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 hosta po wygenerowaniu URL-a) | `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` to przepływy device flow w przeglądarce. Nie są to trasy Unkey.

## `GET /me`

Zalogowane konto. `{ "userId": "...", "email": "...", "name": "..." }`. E-mail i nazwa są pomijane, gdy nie są znane.

## Tworzenie linku 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 JSON przyjmuje dokładnie jedno z: `url`, `text` lub `storageId`, plus opcjonalnie `access` (domyślnie `restricted` \| `link` \| `public`), `slug`, `name`, `tags`, `starts`, `expires`, `maxOpenings`, `password`, `domain`, `previewName`, `previewDescription`, `previewImageStorageId`, `sticky`, `forwardParams`, `utm` (tylko linki URL) oraz `folder` (+ `folderDomain`), jeśli chcesz utworzyć link w folderze. Forma skrócona tworzy jeden wariant o nazwie `main`; `password`, `starts`, `expires` i `maxOpenings` na najwyższym poziomie to bramka linku. Odpowiedź: `{ "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }`.

`GET /links` zwraca jedną stronę, `{ "items": [...], "cursor" }`: `?limit=` to 1-100 (domyślnie 50); przekazuj `?cursor=` z poprzedniej strony, aż będzie `null`. `q` dopasowuje całe słowa (ostatnie jako prefiks), a wyniki są sortowane według trafności. Elementy mają postać `{ id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id }` (wiersze folderów mają dodatkowo `items`); filtr `kind` obsługuje dodatkowo `folder` i `group`, filtr `status` dodatkowo `mixed`, a `folder=<slug>|root` (+ `folderDomain`) listuje jeden folder albo najwyższy poziom. `GET /links/:id` zwraca pełny link z `access` i `variants`; treść (`destinationUrl` / `textContent` / `fileName`) znajduje się w każdym wariancie.

## Przesyłanie pliku

Wygeneruj URL do uploadu (`{uploadUrl,storageId}`), wyślij bajty PUT-em z hosta, a potem w tym samym przepływie utwórz 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}'
```

Małe pliki nadal mogą używać multipart w `POST /links`:

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

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

## Aktualizacja, statystyki, CSV

`PATCH /links/:id` przyjmuje JSON albo multipart. Bajty pliku podmienisz przez `storageId` po `POST /uploads` + PUT z hosta albo przez pole multipart `file` (tylko linki z jednym wariantem). `--status` / `{ "status": "expired" }` jest odrzucane — użyj `expires`. `{ "status": "scheduled" }` jest odrzucane — użyj `starts`. Opcjonalne `maxOpenings` wstrzymuje link po tylu otwarciach; `clearMaxOpenings` usuwa limit. `sticky` (boolean) i `restartSplit` (boolean) sterują przydziałem wariantów; `forwardParams` (boolean) przekazuje query string odwiedzającego, zobacz [Przekazywanie parametrów zapytania](#forward-query-parameters). `access` zmienia, kto może otworzyć link; `resetShareLink: true` wydaje nowy URL udostępniania. Odpowiedź: `{ "id", "url", "access", "status", "variantStatuses" }`.

`GET /links/:id/stats?last=24h` zwraca `visits`, `downloads`, `plays`, `visitsInLast`, `countries`, `referrers`, `variants` (sumy dla każdego wariantu), `visitors` i `crawlers` (`[{ "crawler", "company", "category", "hits", "lastSeen" }]`: boty i podglądy linków, które pobrały link — nigdy nie są liczone jako wizyty; zobacz [Log crawlerów](https://linkdash.dev/pricing.md)).

`GET /links/export` zwraca CSV z kolumnami `slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`, jeden wiersz na wariant (`folder` to slug folderu nadrzędnego; `access` to `restricted`, `link` lub `public`). `POST /links/import` przyjmuje surowy CSV albo multipart `file`; wiersze są grupowane według sluga + domeny (pierwszy wiersz tworzy link z jego wariantem, kolejne dodają warianty; w istniejących linkach aktualizowane są pola, a potem warianty są aktualizowane lub dodawane po nazwie). Wiersze z `kind` `folder` (z `name`) tworzą foldery, a kolumna `folder` umieszcza linki w folderach dopiero wtedy, gdy wszystkie wiersze już istnieją. Puste `access` sprawia, że nowe linki dostają dostęp ograniczony, a istniejące zostają bez zmian.

`DELETE /links/:id` na folderze przyjmuje `?contents=keep` (domyślnie: elementy przechodzą poziom wyżej) albo `?contents=delete` (elementy i foldery w środku też są usuwane).

## Warianty

Każdy link to kontener na jeden lub więcej **wariantów**: treść (`url` | `file` | `text`) plus własna bramka (`password`, `paused`, `starts`, `expires`, `maxOpenings`), `weight` i opcjonalne warunki dla odwiedzających `when`. Do linku należą slug, domena, nazwa, tagi, podgląd, jego własna bramka (która ma pierwszeństwo przed bramkami wariantów), `sticky` (domyślnie `true`) oraz `splitVersion` (zwiększane przez `restartSplit`). Bez `variants` link ma jeden wariant o nazwie `main`. Nazwy: małe litery, cyfry, myślniki w środku, 1–40 znaków, unikalne w obrębie linku. Maksymalnie 20 wariantów na link.

Odwiedzający dostaje jeden wariant: warianty, których `when` pasuje, tworzą pulę (jeśli żaden nie pasuje, pulę tworzą warianty bezwarunkowe), a potem następuje losowanie ważone (sticky hash odwiedzającego + linku + `splitVersion`, w przeciwnym razie losowo). Crawlery dostają pierwszy aktywny wariant bezwarunkowy. `kind` linku z kilkoma wariantami to `group`. `status` linku to status bramki linku, jeśli jest ustawiona, w przeciwnym razie status wspólny dla wszystkich wariantów, a gdy takiego nie ma — `mixed`. `variantStatuses` zlicza `{ active, paused, expired, scheduled }`.

Utwórz kilka wariantów 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żdy wariant: `name` (wymagane), jedno z `url` | `text` | `storageId` (+ `fileName`, `fileType`, `fileSize`), `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when`. Tworzenie przez multipart obsługuje tylko formę skróconą.

| Trasa | Body | Odpowiedź |
| --- | --- | --- |
| `GET /links/:id/variants` | — | tablica wariantów |
| `POST /links/:id/variants` | JSON albo multipart `file`: `name` (wymagane), treść, `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when` | wariant |
| `PATCH /links/:id/variants/:name` | `name` (zmiana nazwy), `url`, `text`, `storageId` / `file`, `password`, `clearPassword`, `starts`, `clearStarts`, `expires`, `clearExpires`, `maxOpenings`, `clearMaxOpenings`, `status` (`active` \| `paused`), `weight`, `when`, `clearWhen`, `utm` | wariant |
| `DELETE /links/:id/variants/:name` | — | `{ "id", "variant", "deleted": true }` (ostatniego wariantu nie da się usunąć) |

Klucze `when` (tablice stringów; każdy ustawiony klucz musi pasować): `countries` (ISO-2), `devices` (`mobile` | `tablet` | `desktop`), `os` (`windows` | `macos` | `android` | `ios` | `linux` | `other`), `browsers` (`edge` | `chrome` | `firefox` | `safari` | `other`), `languages` (prefiks), `referrerHosts` (sufiks hosta).

### Reguły parametrów zapytania

`when.params` to tablica maksymalnie 10 reguł dla query stringa odwiedzającego (`lida.sh/promo?src=newsletter`); każda reguła musi być spełniona. Każda reguła to `{ "key", "op", "value" }`, gdzie `op` to jedno z: `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` to lista rozdzielona `|` lub przecinkami) | `exists` | `missing`. `value` jest wymagane, z wyjątkiem `exists` / `missing`. Klucze rozróżniają wielkość liter, a wartości są porównywane dokładnie.

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

Wartości parametrów są dopasowywane w momencie otwarcia i nigdy nie trafiają do analityki.

### Przekazywanie parametrów zapytania

`forwardParams` (boolean na linku, domyślnie `false`; ustawisz go w `POST /links` i `PATCH /links/:id`, zwraca go `GET /links/:id`) dokleja cały query string odwiedzającego do wariantów URL. Wartości od odwiedzającego nadpisują zapisane, łącznie z `utm`. Warianty plikowe i tekstowe to ignorują. To routing, a nie kontrola dostępu: każdy może dodać parametry. Wartości parametrów nie są zapisywane w analityce.

## Foldery

Folder to link, który listuje elementy, które do niego wrzucisz. Model opisuje strona [Foldery](/pl/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 | Body | Odpowiedź |
| --- | --- | --- |
| `POST /links` | `{ "kind": "folder", "name" }` plus zwykłe pola linku; bez `url`, `text`, `storageId` ani `variants` | utworzony folder |
| `POST /links/:id/move` | `{ "folder": "<slug>" }` albo `{ "folder": null }` dla najwyższego poziomu, opcjonalnie `folderDomain` | `{ "id", "folder" }` |
| `POST /links/:id/copy` | — | `{ "id", "url", "access", "kind", "variants", "folder", … }` (ten sam dostęp, nowy URL udostępniania, bez osób) |

Przeniesienie i kopiowanie liczą się jako jedno zdarzenie każde. Nieznany slug folderu zwraca `404` (`Folder "<slug>" not found`); slug, który nie jest folderem, albo przeniesienie folderu do niego samego lub do folderu pod nim zwraca `400`. Foldery można zagnieżdżać maksymalnie na 32 poziomy.

## Dostęp i udostępnianie

Każdy link i folder ma `access`: `restricted` (domyślnie; właściciel i osoby, którym go udostępniono, po zalogowaniu, pod `https://linkdash.dev/s/<token>`), `link` (każdy, kto ma ten URL) albo `public` (każdy, pod krótkim URL-em). Ustawisz to w `POST /links` lub `PATCH /links/:id`. Przekaż `"access": "public"` dla linków, które mają być publikowane publicznie. Jak działają foldery i osoby z dostępem do podglądu, opisuje strona [Udostępnianie i dostęp](/pl/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 | Body | Odpowiedź |
| --- | --- | --- |
| `POST /links/:id/shares` | `{ "emails": [...] }` (1–50 adresów 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" }` (wszystkie twoje udostępnienia) |
| `GET /shared` | — | `{ "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }` |
| `DELETE /shared/:id` | — | `{ "_id", "left": true }` (`:id` to `_id` lub token udostępniania z `GET /shared`) |
| `POST /links/:id/reset-link` | — | `{ "id", "access", "url" }` |

`POST /links/:id/shares` przyjmuje `"role": "editor"` dla edytorów. Edytorzy mogą zmieniać elementy i widzą statystyki oraz aktywność, ale nie mają dostępu do haseł, sluga, domeny, ustawień dostępu ani udostępniania i nie mogą usuwać, przenosić ani kopiować (`403`); jako `:id` używają `_id` elementu lub tokena udostępniania, a wariant chroniony hasłem pozostaje `locked: true` do czasu `POST /links/:id/unlock` (30 minut, dziesięć błędnych haseł na godzinę, potem `429`). Zapis po tym, jak ktoś inny już zapisał zmiany, zwraca `409` tylko wtedy, gdy żądanie wysyła `expectedVersion`. Wszystkie trasy udostępniania przyjmują `?domain=`, gdy slug się powtarza. `accepted` ma wartość `false`, dopóki ten adres e-mail nie ma zweryfikowanego konta; `viaFolder` oznacza, że dostęp pochodzi z folderu wyżej. Maksymalnie 200 osób na element i 100 e-maili z zaproszeniami na konto dziennie. `GET /shares` i `GET /shared` zwracają wyniki stronami: `?limit=` to 1-100 (domyślnie 50); przekazuj `?cursor=` z poprzedniej strony, aż `cursor` będzie `null`. Share, unshare i reset liczą się jako jedno zdarzenie każde; opuszczenie udostępnienia się nie liczy. Dostęp przez udostępniony folder wyżej pozostaje po opuszczeniu.

## Błędy

| Status | Kiedy |
| --- | --- |
| 400 | Błąd walidacji, brak body, pomieszane rodzaje tworzenia |
| 401 | Brak lub nieprawidłowy klucz bearer |
| 404 | Nieznany slug, domena lub folder |
| 409 | Slug zajęty (`code: "slug_taken"`) |
| 429 | Osiągnięto miesięczny limit zdarzeń |
| 503 | Klucze API nie są skonfigurowane w tym wdrożeniu |

Te endpointy opisują strony [webhooki](/pl/webhooks) i [własne domeny](/pl/domains).
