HTTP API
REST pod https://api.linkdash.dev/v1 z kluczem bearer z dashboardu. Te same operacje co w CLI i MCP.
Bazowy URL: https://api.linkdash.dev/v1
Uwierzytelnianie: Authorization: Bearer ldash_... (klucze utworzysz w Panel → Klucze API). Nie wymyślaj kluczy.
Dokumentacja CLI: CLI. MCP: MCP. Cennik / limity: Cennik. Discovery (bez uwierzytelniania): GET https://api.linkdash.dev/v1. Czysty markdown: 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,textlubstorageId(poPOST /uploads), albo tablicęvariants(zobacz Warianty), albo"kind": "folder"zname(zobacz Foldery). Wygenerowanie URL-a do uploadu zwraca{ "uploadUrl", "storageId" }. Host wysyła bajty PUT-em nauploadUrl. Małe pliki nadal mogą używać multipartfilewPOST /links. - Czasy trwania:
7d,24h,30m,1walbo data ISO. Pola:expires/expiresAt,starts/startsAt. - Limit otwarć: opcjonalna dodatnia liczba całkowita
maxOpenings. Link zostaje wstrzymany po tylu udanych otwarciach. ZwiększmaxOpeningsalbo użyjclearMaxOpenings, ż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 JSONdomain. - Błędy:
{ "error": "..." }plus opcjonalnycode. Zajęte slugilida.shzwracają409zcode: "slug_taken". - Dostęp: nowe linki i foldery są
restricted, chyba że body ustawiaaccess(zobacz Dostęp i udostępnianie).urlw 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" } |
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
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:
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:
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. 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).
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:
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.
{ "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.
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.
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 i własne domeny.

