Przejdź do treści
LinkdashLinkdash
Polski
Esc
↑↓nawigacja↵otwórz⌘Jpodgląd
Na tej stronie

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, text lub storageId (po POST /uploads), albo tablicę variants (zobacz Warianty), albo "kind": "folder" z name (zobacz Foldery). 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). 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" }
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.

Czy ta strona była pomocna?