HTTP API
REST på https://api.linkdash.dev/v1 med en bearer-nøgle fra dashboardet. Samme operationer som CLI'en og MCP.
Base-URL: https://api.linkdash.dev/v1
Auth: Authorization: Bearer ldash_... (opret nøgler under Dashboard → API-nøgler). Find ikke selv på nøgler.
CLI-reference: CLI. MCP: MCP. Priser / kvoter: Priser. Discovery (uden auth): GET https://api.linkdash.dev/v1. Ren markdown: api.md.
Offentlige id’er er slugs (deck, k3m9xq), ikke Convex _id. JSON-feltnavne matcher CLI’ens stdout (id, url, kind, …).
Konventioner
- JSON
Content-Type: application/json, medmindre andet er angivet. - Create tager præcis én af
url,textellerstorageIdefterPOST /uploads, eller etvariants-array (se Varianter), eller"kind": "folder"med etname(se Mapper). Mint returnerer{ "uploadUrl", "storageId" }. Værten PUT’er bytes tiluploadUrl. Små filer kan stadig bruge multipartfilepåPOST /links. - Varigheder:
7d,24h,30m,1weller en ISO-dato. Felter:expires/expiresAt,starts/startsAt. - Grænse for åbninger: valgfrit positivt heltal
maxOpenings. Linket pauses efter så mange vellykkede åbninger. HævmaxOpenings, eller brugclearMaxOpenings, for at servere det igen. UdeladmaxOpeningsfor ubegrænset. - Hvis en slug findes på to af ejerens domæner, så send
?domain=/ JSONdomain. - Fejl:
{ "error": "..." }plus valgfricode. Optagnelida.sh-slugs returnerer409medcode: "slug_taken". - Adgang: nye links og mapper er
restricted, medmindre body sætteraccess(se Adgang og deling).urli svar er delings-URL’en (https://linkdash.dev/s/<token>), medmindre linket er offentligt – så er det den korte URL. - Skrivninger tæller med i den månedlige eventkvote (share, unshare og reset inklusive). List / get / stats / export / shares list / shared / webhook list/get gør ikke. Indtag af visit / download / play tæller stadig.
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 (uden 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 (uden 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 |
| (værten laver 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 og auth logout er device flows i browseren. De er ikke Unkey-ruter.
GET /me
Den indloggede konto. { "userId": "...", "email": "...", "name": "..." }. Email og name udelades, når de er ukendte.
Opret et URL-link
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-body tager præcis én af url, text eller storageId, plus valgfri access (restricted standard | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (kun URL-links) og folder (+ folderDomain) for at oprette linket i en mappe. Kortformen opretter én variant med navnet main; password, starts, expires og maxOpenings på topniveau er linkets gate. Svar: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.
GET /links returnerer én side, { "items": [...], "cursor" }: ?limit= er 1-100 (standard 50); send ?cursor= fra forrige side, indtil den er null. q matcher hele ord (det sidste som præfiks), rangeret efter relevans. Items er { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (mapperækker tilføjer items); kind-filteret tilføjer folder og group, status-filteret tilføjer mixed, og folder=<slug>|root (+ folderDomain) lister én mappe eller topniveauet. GET /links/:id returnerer hele linket med access og variants; indholdet (destinationUrl / textContent / fileName) ligger på hver variant.
Upload en fil
Mint en upload-URL ({uploadUrl,storageId}), PUT bytes fra værten, og opret så linket i samme flow:
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 stadig bruge 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"
Valgfri multipart-felter: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.
Opdatering, stats, CSV
PATCH /links/:id er JSON eller multipart. Erstat filens bytes med storageId efter POST /uploads + PUT fra værten, eller med multipart-feltet file (kun links med én variant). --status / { "status": "expired" } afvises – brug expires. { "status": "scheduled" } afvises – brug starts. Valgfri maxOpenings pauser linket efter så mange åbninger; clearMaxOpenings fjerner grænsen. sticky (boolean) og restartSplit (boolean) styrer, hvordan varianter tildeles; forwardParams (boolean) videresender den besøgendes query string, se Videresend query-parametre. access ændrer, hvem der kan åbne det; resetShareLink: true udsteder en ny delings-URL. Svar: { "id", "url", "access", "status", "variantStatuses" }.
GET /links/:id/stats?last=24h returnerer visits, downloads, plays, visitsInLast, countries, referrers, variants (totaler pr. variant), visitors og crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: bots og linkpreviews, der har hentet linket, og som aldrig tælles som besøg; se Crawler-log).
GET /links/export er CSV med kolonnerne slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, én række pr. variant (folder er slug’en på den mappe, linket ligger i; access er restricted, link eller public). POST /links/import accepterer rå CSV eller multipart file; rækker grupperes efter slug + domæne (første række opretter linket med dets variant, flere rækker tilføjer varianter; for eksisterende links opdateres felterne, og derefter opdateres eller tilføjes varianter efter navn). Rækker med kind folder (med et name) opretter mapper, og folder-kolonnen placerer links, når alle rækker findes. En tom access gør nye links restricted og lader eksisterende links være, som de er.
DELETE /links/:id på en mappe tager ?contents=keep (standard: elementerne flyttes et niveau op) eller ?contents=delete (elementer og mapper indeni slettes også).
Varianter
Hvert link er en container med én eller flere varianter: indhold (url | file | text) plus sin egen gate (password, paused, starts, expires, maxOpenings), en weight og valgfrie betingelser for besøgende, when. Linket ejer slug, domæne, navn, tags, preview, sin egen gate (som vinder over variant-gates), sticky (standard true) og splitVersion (øges af restartSplit). Uden variants har et link én variant med navnet main. Navne: små bogstaver, cifre og bindestreger inde i navnet, 1–40 tegn, unikke pr. link. Maks. 20 varianter pr. link.
En besøgende får én variant: varianter, hvis when matcher, udgør puljen (matcher ingen, gør de ubetingede varianter det), og derefter foretages et vægtet valg (sticky hash af besøgende + link + splitVersion, ellers tilfældigt). Crawlere får den første aktive ubetingede variant. Linkets kind er group, når der er flere varianter. Linkets status er linkets gate, når den er sat, ellers den status, alle varianter deler, ellers mixed. variantStatuses tæller { active, paused, expired, scheduled }.
Opret flere varianter på én gang:
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"]}}]}'
Hver variant: name (påkrævet), én af url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. Multipart-create understøtter kun kortformen.
| Rute | Body | Svar |
|---|---|---|
GET /links/:id/variants |
— | array af varianter |
POST /links/:id/variants |
JSON eller multipart file: name (påkrævet), indhold, password, starts, expires, maxOpenings, utm, weight, when |
varianten |
PATCH /links/:id/variants/:name |
name (omdøb), 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 sidste variant kan ikke slettes) |
when-nøgler (arrays af strenge; alle satte nøgler skal matche): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (præfiks), referrerHosts (host-suffiks).
Regler for query-parametre
when.params er et array med op til 10 regler for den besøgendes query string (lida.sh/promo?src=newsletter); alle regler skal være opfyldt. Hver regel er { "key", "op", "value" }, hvor op er en af equals | notEquals | includes | startsWith | endsWith | in (value er en liste adskilt af | eller komma) | exists | missing. value er påkrævet, undtagen for exists / missing. Nøgler skelner mellem store og små bogstaver, og værdier sammenlignes eksakt.
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
Parameterværdier matches, når linket åbnes, og gemmes aldrig i analytics.
Videresend query-parametre
forwardParams (boolean på linket, standard false; kan sættes på POST /links og PATCH /links/:id og returneres af GET /links/:id) tilføjer den besøgendes hele query string til URL-varianter. Den besøgendes værdier overskriver de gemte, utm inklusive. Fil- og tekstvarianter ignorerer det. Det her er routing, ikke adgangskontrol: alle kan tilføje parametre. Parameterværdier gemmes ikke i analytics.
Mapper
En mappe er et link, der viser de elementer, du lægger i den. Se Mapper for modellen.
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_..."
| Rute | Body | Svar |
|---|---|---|
POST /links |
{ "kind": "folder", "name" } plus de sædvanlige linkfelter; ingen url, text, storageId eller variants |
den oprettede mappe |
POST /links/:id/move |
{ "folder": "<slug>" } eller { "folder": null } for topniveauet, valgfri folderDomain |
{ "id", "folder" } |
POST /links/:id/copy |
— | { "id", "url", "access", "kind", "variants", "folder", … } (samme adgang, ny delings-URL, ingen personer) |
Move og copy tæller hver som ét event. En ukendt mappe-slug returnerer 404 (Folder "<slug>" not found); en slug, der ikke er en mappe, eller et forsøg på at flytte en mappe ind i sig selv eller i en mappe under den, returnerer 400. Mapper kan højst indlejres 32 niveauer dybt.
Adgang og deling
Hvert link og hver mappe har access: restricted (standard; ejeren og de personer, det er delt med, når de er logget ind, på https://linkdash.dev/s/<token>), link (alle med den URL) eller public (alle, på den korte URL). Sæt det på POST /links eller PATCH /links/:id. Send "access": "public" for links, der skal deles offentligt. Se Deling og adgang for, hvordan mapper og seere fungerer.
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_..."
| Rute | Body | Svar |
|---|---|---|
POST /links/:id/shares |
{ "emails": [...] } (1–50 e-mails) |
{ "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" } (alt, du har delt) |
GET /shared |
— | { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" } |
DELETE /shared/:id |
— | { "_id", "left": true } (:id er _id eller delingstokenet fra GET /shared) |
POST /links/:id/reset-link |
— | { "id", "access", "url" } |
POST /links/:id/shares tager "role": "editor" for redaktører. Redaktører kan ændre elementer og se stats og aktivitet, men aldrig adgangskoder, slug, domæne, adgang, deling, sletning, flytning eller kopiering (403); de bruger elementets _id eller delingstoken som :id, og en adgangskodebeskyttet variant forbliver locked: true indtil POST /links/:id/unlock (30 minutter, ti forkerte adgangskoder i timen, derefter 429). Gemmer du, efter en anden har gemt, får du kun 409, når requesten sender expectedVersion. Alle delingsruter tager ?domain=, når slug’en går igen. accepted er false, indtil den e-mail har en verificeret konto; viaFolder betyder, at adgangen kommer fra en mappe længere oppe. Op til 200 personer pr. element og 100 invitationsmails pr. konto pr. dag. GET /shares og GET /shared returnerer én side ad gangen: ?limit= er 1-100 (standard 50); send ?cursor= fra forrige side, indtil cursor er null. Share, unshare og reset tæller hver som ét event; at forlade et element gør ikke. Adgang gennem en delt mappe længere oppe bevares, efter du har forladt elementet.
Fejl
| Status | Hvornår |
|---|---|
| 400 | Validering, manglende body, blandede create-typer |
| 401 | Manglende eller ugyldig bearer-nøgle |
| 404 | Ukendt slug, domæne eller mappe |
| 409 | Slug er optaget (code: "slug_taken") |
| 429 | Månedlig eventkvote er nået |
| 503 | API-nøgler er ikke konfigureret på denne deployment |
Se webhooks og custom domæner for de endpoints.

