HTTP API
REST på https://api.linkdash.dev/v1 med en bearer-nyckel från dashboarden. Samma operationer som CLI:n och MCP.
Bas-URL: https://api.linkdash.dev/v1
Autentisering: Authorization: Bearer ldash_... (skapa nycklar under Dashboard → API-nycklar). Hitta inte på nycklar.
CLI-referens: CLI. MCP: MCP. Priser / kvoter: Priser. Discovery (ingen autentisering): GET https://api.linkdash.dev/v1. Ren markdown: api.md.
Publika id är slugs (deck, k3m9xq), inte Convex _id. JSON-fältnamnen matchar CLI stdout (id, url, kind, …).
Konventioner
- JSON
Content-Type: application/jsonom inget annat anges. - Create tar exakt ett av
url,textellerstorageIdefterPOST /uploads, eller envariants-array (se Varianter), eller"kind": "folder"med ettname(se Mappar). Mint returnerar{ "uploadUrl", "storageId" }. Hosten skickar byten med PUT tilluploadUrl. Små filer kan fortfarande använda multipartfilepåPOST /links. - Varaktigheter:
7d,24h,30m,1weller ett ISO-datum. Fält:expires/expiresAt,starts/startsAt. - Öppningsgräns: valfritt positivt heltal
maxOpenings. Länken pausas efter så många lyckade öppningar. HöjmaxOpenings, eller användclearMaxOpenings, för att servera den igen. UtelämnamaxOpeningsför obegränsat. - Om en slug finns på två av ägarens domäner skickar du
?domain=/ JSONdomain. - Fel:
{ "error": "..." }plus valfricode. Upptagnalida.sh-slugs returnerar409medcode: "slug_taken". - Åtkomst: nya länkar och mappar är
restrictedom inte bodyn sätteraccess(se Åtkomst och delning).urli svaren är delnings-URL (https://linkdash.dev/s/<token>) om inte länken är publik, då är det den korta URL. - Skrivningar räknas mot den månatliga eventkvoten (delning, borttagen delning och återställning inräknade). List / get / stats / export / shares list / shared / webhook list/get räknas inte. Besök / nedladdningar / uppspelningar räknas fortfarande.
Endpoints
| 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 (utan 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 (utan 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 |
| (host-PUT efter mint) | 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 och auth logout är device flows i webbläsaren. De är inte Unkey-routes.
GET /me
Inloggat konto. { "userId": "...", "email": "...", "name": "..." }. E-post och namn utelämnas när de är okända.
Skapa en URL-länk
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"}'
JSON-bodyn tar exakt ett av url, text eller storageId, plus valfria access (restricted som standard | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (bara URL-länkar) och folder (+ folderDomain) för att skapa länken i en mapp. Kortformen skapar en variant som heter main; password, starts, expires och maxOpenings på toppnivå är länkens spärr. Svar: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.
GET /links returnerar en sida, { "items": [...], "cursor" }: ?limit= är 1-100 (standard 50); skicka ?cursor= från föregående sida tills den är null. q matchar hela ord (det sista som prefix), rankat efter relevans. Posterna är { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (mapprader lägger till items); kind-filtret lägger till folder och group, status-filtret lägger till mixed, och folder=<slug>|root (+ folderDomain) listar en mapp eller toppnivån. GET /links/:id returnerar hela länken med access och variants; innehållet (destinationUrl / textContent / fileName) ligger på varje variant.
Ladda upp en fil
Minta en uppladdnings-URL ({uploadUrl,storageId}), skicka byten med PUT från hosten och skapa sedan länken i samma flöde:
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}'
Små filer kan fortfarande använda multipart på POST /links:
curl https://api.linkdash.dev/v1/links \
-H "Authorization: Bearer ldash_..." \
-F "file=@./deck.pdf" \
-F "expires=7d" \
-F "slug=deck"
Valfria multipart-fält: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.
Uppdatering, statistik, CSV
PATCH /links/:id tar JSON eller multipart. Byt ut filens bytes med storageId efter POST /uploads + host-PUT, eller med multipart-fältet file (bara länkar med en enda variant). --status / { "status": "expired" } avvisas – använd expires. { "status": "scheduled" } avvisas – använd starts. Valfri maxOpenings pausar länken efter så många öppningar; clearMaxOpenings tar bort gränsen. sticky (boolean) och restartSplit (boolean) styr hur varianter tilldelas; forwardParams (boolean) vidarebefordrar besökarens query string, se Vidarebefordra query-parametrar. access ändrar vem som kan öppna den; resetShareLink: true ger en ny delnings-URL. Svar: { "id", "url", "access", "status", "variantStatuses" }.
GET /links/:id/stats?last=24h returnerar visits, downloads, plays, visitsInLast, countries, referrers, variants (totaler per variant), visitors och crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: botar och länkförhandsvisningar som har hämtat länken, räknas aldrig som besök; se Crawlerlogg).
GET /links/export är CSV med kolumnerna slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, en rad per variant (folder är slugen för mappen som innehåller länken; access är restricted, link eller public). POST /links/import tar emot rå CSV eller multipart file; rader grupperas efter slug + domän (första raden skapar länken med sin variant, fler rader lägger till varianter; befintliga länkar får sina fält uppdaterade, sedan uppdateras eller läggs varianter till efter namn). Rader med kind folder (med ett name) skapar mappar, och kolumnen folder placerar länkarna när alla rader finns. En tom access gör nya länkar begränsade och lämnar befintliga länkar som de är.
DELETE /links/:id på en mapp tar ?contents=keep (standard: posterna flyttas upp en nivå) eller ?contents=delete (poster och mappar i den raderas också).
Varianter
Varje länk är en behållare för en eller flera varianter: innehåll (url | file | text) plus en egen spärr (password, paused, starts, expires, maxOpenings), en weight och valfria besökarvillkor when. Länken äger slug, domän, namn, taggar, förhandsvisning, sin egen spärr (som går före variantspärrarna), sticky (standard true) och splitVersion (räknas upp av restartSplit). Utan variants har en länk en variant som heter main. Namn: gemener, siffror, bindestreck inuti, 1–40 tecken, unika per länk. Max 20 varianter per länk.
En besökare får en variant: varianter vars when matchar bildar poolen (om ingen matchar gör de villkorslösa varianterna det), sedan görs ett viktat val (sticky hash av besökare + länk + splitVersion, annars slumpmässigt). Crawlers får den första aktiva villkorslösa varianten. Länkens kind är group när den har flera varianter. Länkens status är länkspärren när den är satt, annars den status som alla varianter delar, annars mixed. variantStatuses räknar { active, paused, expired, scheduled }.
Skapa flera varianter på en gång:
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"]}}]}'
Varje variant: name (obligatoriskt), ett av url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. Create via multipart stöder bara kortformen.
| Route | Body | Svar |
|---|---|---|
GET /links/:id/variants |
— | array med varianter |
POST /links/:id/variants |
JSON eller multipart file: name (obligatoriskt), innehåll, password, starts, expires, maxOpenings, utm, weight, when |
varianten |
PATCH /links/:id/variants/:name |
name (byt namn), url, text, storageId / file, password, clearPassword, starts, clearStarts, expires, clearExpires, maxOpenings, clearMaxOpenings, status (active | paused), weight, when, clearWhen, utm |
varianten |
DELETE /links/:id/variants/:name |
— | { "id", "variant", "deleted": true } (den sista varianten kan inte raderas) |
when-nycklar (arrayer av strängar; varje nyckel som är satt måste matcha): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (prefix), referrerHosts (värdsuffix).
Regler för query-parametrar
when.params är en array med upp till 10 regler för besökarens query string (lida.sh/promo?src=newsletter); alla regler måste gälla. Varje regel är { "key", "op", "value" } där op är ett av equals | notEquals | includes | startsWith | endsWith | in (value är en lista separerad med | eller komma) | exists | missing. value krävs utom för exists / missing. Nycklar är skiftlägeskänsliga och värden jämförs exakt.
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
Parametervärden matchas när länken öppnas och lagras aldrig i analysdatan.
Vidarebefordra query-parametrar
forwardParams (boolean på länken, standard false; kan sättas på POST /links och PATCH /links/:id, returneras av GET /links/:id) lägger till besökarens hela query string på URL-varianter. Besökarens värden skriver över de lagrade, utm inräknat. Fil- och textvarianter ignorerar den. Det här är routing, inte åtkomstkontroll: vem som helst kan lägga till parametrar. Parametervärden lagras inte i analysdatan.
Mappar
En mapp är en länk som listar posterna du lägger i den. Se Mappar för hur modellen fungerar.
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_..."
| Route | Body | Svar |
|---|---|---|
POST /links |
{ "kind": "folder", "name" } plus de vanliga länkfälten; ingen url, text, storageId eller variants |
den skapade mappen |
POST /links/:id/move |
{ "folder": "<slug>" } eller { "folder": null } för toppnivån, valfri folderDomain |
{ "id", "folder" } |
POST /links/:id/copy |
— | { "id", "url", "access", "kind", "variants", "folder", … } (samma åtkomst, ny delnings-URL, inga personer) |
Flytt och kopiering räknas som ett event var. En okänd mapp-slug returnerar 404 (Folder "<slug>" not found); en slug som inte är en mapp, eller att flytta en mapp in i sig själv eller i en mapp under den, returnerar 400. Mappar kan nästlas högst 32 nivåer djupt.
Åtkomst och delning
Varje länk och mapp har access: restricted (standard; ägaren och de personer den delats med, inloggade, på https://linkdash.dev/s/<token>), link (vem som helst med den URL) eller public (vem som helst, på den korta URL). Sätt den på POST /links eller PATCH /links/:id. Skicka "access": "public" för länkar som ska publiceras offentligt. Se Delning och åtkomst för hur mappar och tittare fungerar.
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_..."
| Route | Body | Svar |
|---|---|---|
POST /links/:id/shares |
{ "emails": [...] } (1–50 e-postadresser) |
{ "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" } (allt du har delat) |
GET /shared |
— | { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" } |
DELETE /shared/:id |
— | { "_id", "left": true } (:id är _id eller delningstoken från GET /shared) |
POST /links/:id/reset-link |
— | { "id", "access", "url" } |
POST /links/:id/shares tar "role": "editor" för redaktörer. Redaktörer kan ändra poster och se statistik och aktivitet, men aldrig lösenord, slug, domän, åtkomst, delning, radering, flytt eller kopiering (403). De använder postens _id eller delningstoken som :id, och en lösenordsskyddad variant förblir locked: true tills POST /links/:id/unlock (30 minuter, tio felaktiga lösenord per timme, sedan 429). Att spara efter att någon annan har sparat ger 409 bara när requesten skickar expectedVersion. Alla delningsroutes tar ?domain= när slugen förekommer på flera domäner. accepted är false tills den e-postadressen har ett verifierat konto; viaFolder betyder att åtkomsten kommer från en mapp längre upp. Upp till 200 personer per post och 100 inbjudningsmejl per konto och dag. GET /shares och GET /shared returnerar en sida i taget: ?limit= är 1-100 (standard 50); skicka ?cursor= från föregående sida tills cursor är null. Delning, borttagen delning och återställning räknas som ett event var; att lämna räknas inte. Åtkomst via en delad mapp längre upp finns kvar efter att du har lämnat.
Fel
| Status | När |
|---|---|
| 400 | Validering, saknad body, blandade create-typer |
| 401 | Saknad eller ogiltig bearer-nyckel |
| 404 | Okänd slug, domän eller mapp |
| 409 | Slugen är upptagen (code: "slug_taken") |
| 429 | Den månatliga eventkvoten är nådd |
| 503 | API-nycklar är inte konfigurerade i den här driftsättningen |
Se webhooks och egna domäner för de endpoints som hör dit.

