HTTP API
REST på https://api.linkdash.dev/v1 med en bearer-nøkkel fra dashbordet. Samme operasjoner som CLI og MCP.
Base-URL: https://api.linkdash.dev/v1
Autentisering: Authorization: Bearer ldash_... (opprett nøkler under Dashbord → API-nøkler). Ikke dikt opp nøkler.
CLI-referanse: CLI. MCP: MCP. Priser / kvoter: Priser. Oppdagelse (uten autentisering): GET https://api.linkdash.dev/v1. Ren markdown: api.md.
Offentlige id-er er slugs (deck, k3m9xq), ikke Convex _id. JSON-feltnavn samsvarer med CLI-stdout (id, url, kind, …).
Konvensjoner
- JSON
Content-Type: application/jsonmed mindre annet er oppgitt. - Opprettelse tar nøyaktig én av
url,textellerstorageIdetterPOST /uploads, eller envariants-array (se Varianter), eller"kind": "folder"med etname(se Mapper). Mint returnerer{ "uploadUrl", "storageId" }. Verten PUT-er bytene tiluploadUrl. Små filer kan fortsatt bruke multipartfilepåPOST /links. - Varigheter:
7d,24h,30m,1weller en ISO-dato. Felter:expires/expiresAt,starts/startsAt. - Åpningsgrense: valgfritt positivt heltall
maxOpenings. Lenken settes på pause etter så mange vellykkede åpninger. ØkmaxOpenings, eller brukclearMaxOpenings, for å servere den igjen. UtelatmaxOpeningsfor ubegrenset. - Hvis en slug finnes på to av eierens domener, send
?domain=/ JSONdomain. - Feil:
{ "error": "..." }pluss valgfricode. Opptattelida.sh-slugs returnerer409medcode: "slug_taken". - Tilgang: nye lenker og mapper er
restrictedmed mindre bodyen setteraccess(se Tilgang og deling).urli svar er delings-URL-en (https://linkdash.dev/s/<token>) med mindre lenken er offentlig, da er det den korte URL-en. - Skriveoperasjoner teller mot den månedlige hendelseskvoten (deling, oppheving av deling og tilbakestilling inkludert). List / get / stats / export / shares list / shared / webhook list/get gjør det ikke. Inntak av besøk / nedlastinger / avspillinger teller fortsatt.
Endepunkter
| 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 (uten 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 (uten 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 fra verten etter 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 enhetsflyter i nettleseren. De er ikke Unkey-ruter.
GET /me
Innlogget konto. { "userId": "...", "email": "...", "name": "..." }. E-post og navn utelates når de er ukjente.
Opprett en URL-lenke
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-bodyen tar nøyaktig én av url, text eller storageId, pluss valgfrie access (restricted standard | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (kun URL-lenker) og folder (+ folderDomain) for å opprette i en mappe. Kortformen oppretter én variant kalt main; password, starts, expires og maxOpenings på toppnivå er lenkens sperre. 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 til den er null. q matcher hele ord (det siste som prefiks), rangert etter relevans. Elementene er { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (mapperader legger til items); kind-filteret legger til folder og group, status-filteret legger til mixed, og folder=<slug>|root (+ folderDomain) lister én mappe eller toppnivået. GET /links/:id returnerer hele lenken med access og variants; innholdet (destinationUrl / textContent / fileName) ligger på hver variant.
Last opp en fil
Mint en opplastings-URL ({uploadUrl,storageId}), PUT bytene fra verten, og opprett deretter lenken i samme flyt:
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 fortsatt bruke 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"
Valgfrie multipart-felter: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.
Oppdatering, statistikk, CSV
PATCH /links/:id er JSON eller multipart. Erstatt filbytene med storageId etter POST /uploads + PUT fra verten, eller med multipart-feltet file (kun lenker med én variant). --status / { "status": "expired" } avvises – bruk expires. { "status": "scheduled" } avvises – bruk starts. Valgfri maxOpenings setter lenken på pause etter så mange åpninger; clearMaxOpenings fjerner grensen. sticky (boolean) og restartSplit (boolean) styrer variantfordelingen; forwardParams (boolean) videresender den besøkendes query-streng, se Videresend query-parametere. access endrer hvem som kan åpne den; resetShareLink: true utsteder 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 per variant), visitors og crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: roboter og lenkeforhåndsvisninger som hentet lenken, aldri telt som besøk; se Crawler-logg).
GET /links/export er CSV med kolonnene slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, én rad per variant (folder er sluggen til mappen som inneholder den; access er restricted, link eller public). POST /links/import godtar rå CSV eller multipart file; radene grupperes etter slug + domene (første rad oppretter lenken med varianten sin, flere rader legger til varianter; eksisterende lenker får feltene oppdatert, og deretter oppdateres eller legges varianter til etter navn). Rader med kind folder (med et name) oppretter mapper, og folder-kolonnen plasserer lenker etter at alle radene finnes. En tom access gjør nye lenker begrensede og lar eksisterende lenker være som de er.
DELETE /links/:id på en mappe tar ?contents=keep (standard: elementene flyttes ett nivå opp) eller ?contents=delete (elementer og mapper inni slettes også).
Varianter
Hver lenke er en beholder for én eller flere varianter: innhold (url | file | text) pluss en egen sperre (password, paused, starts, expires, maxOpenings), en weight og valgfrie betingelser for besøkende, when. Lenken eier slug, domene, navn, tagger, forhåndsvisning, sin egen sperre (som går foran variantsperrene), sticky (standard true) og splitVersion (økes av restartSplit). Uten variants har en lenke én variant kalt main. Navn: små bokstaver, sifre og bindestreker inni navnet, 1–40 tegn, unike per lenke. Maks 20 varianter per lenke.
En besøkende får én variant: variantene der when matcher, utgjør utvalget (hvis ingen matcher, brukes de ubetingede variantene), deretter gjøres et vektet valg (sticky hash av besøkende + lenke + splitVersion, ellers tilfeldig). Crawlere får den første aktive ubetingede varianten. Lenkens kind er group når den har flere varianter. Lenkens status er lenkesperren når den er satt, ellers statusen alle variantene deler, ellers mixed. variantStatuses teller { active, paused, expired, scheduled }.
Opprett flere varianter samtidig:
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åkrevd), én av url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. Multipart-opprettelse støtter bare kortformen.
| Rute | Body | Svar |
|---|---|---|
GET /links/:id/variants |
— | array med varianter |
POST /links/:id/variants |
JSON eller multipart file: name (påkrevd), innhold, password, starts, expires, maxOpenings, utm, weight, when |
varianten |
PATCH /links/:id/variants/:name |
name (gi nytt navn), 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 siste varianten kan ikke slettes) |
when-nøkler (arrays med strenger; alle nøkler som er satt, må matche): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (prefiks), referrerHosts (vertssuffiks).
Regler for query-parametere
when.params er en array med opptil 10 regler for den besøkendes query-streng (lida.sh/promo?src=newsletter); alle reglene må være oppfylt. Hver regel er { "key", "op", "value" } der op er én av equals | notEquals | includes | startsWith | endsWith | in (value er en liste skilt med | eller komma) | exists | missing. value er påkrevd, unntatt for exists / missing. Nøkler skiller mellom store og små bokstaver, og verdier sammenlignes eksakt.
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
Parameterverdier matches når lenken åpnes, og lagres aldri i analysene.
Videresend query-parametere
forwardParams (boolean på lenken, standard false; kan settes på POST /links og PATCH /links/:id, og returneres av GET /links/:id) legger hele query-strengen til den besøkende på URL-varianter. Verdiene fra den besøkende overstyrer lagrede verdier, også utm. Fil- og tekstvarianter ignorerer den. Dette er ruting, ikke tilgangskontroll: hvem som helst kan legge til parametere. Parameterverdier lagres ikke i analysene.
Mapper
En mappe er en lenke som lister elementene du legger 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" } pluss de vanlige lenkefeltene; ingen url, text, storageId eller variants |
den opprettede mappen |
POST /links/:id/move |
{ "folder": "<slug>" } eller { "folder": null } for toppnivået, valgfri folderDomain |
{ "id", "folder" } |
POST /links/:id/copy |
— | { "id", "url", "access", "kind", "variants", "folder", … } (samme tilgang, ny delings-URL, ingen personer) |
Flytting og kopiering teller hver som én hendelse. En ukjent mappe-slug returnerer 404 (Folder "<slug>" not found); en slug som ikke er en mappe, eller å flytte en mappe inn i seg selv eller i en mappe under den, returnerer 400. Mapper kan nøstes maks 32 nivåer dypt.
Tilgang og deling
Hver lenke og mappe har access: restricted (standard; eieren og personene den er delt med, innlogget, på https://linkdash.dev/s/<token>), link (alle som har den URL-en) eller public (alle, på den korte URL-en). Sett den på POST /links eller PATCH /links/:id. Send "access": "public" for lenker som skal publiseres offentlig. Se Deling og tilgang for hvordan mapper og lesere 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-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" } (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 tar "role": "editor" for redaktører. Redaktører kan endre elementer og se statistikk og aktivitet, men aldri passord, slug, domene, tilgang, deling, sletting, flytting eller kopiering (403); de bruker elementets _id eller delingstoken som :id, og en passordbeskyttet variant forblir locked: true til POST /links/:id/unlock (30 minutter, ti feil passord i timen, deretter 429). Å lagre etter at noen andre har lagret gir 409 bare når forespørselen sender expectedVersion. Alle delingsruter tar ?domain= når sluggen går igjen. accepted er false til den e-postadressen har en verifisert konto; viaFolder betyr at tilgangen kommer fra en mappe lenger opp. Opptil 200 personer per element og 100 invitasjons-e-poster per konto per dag. GET /shares og GET /shared returnerer én side om gangen: ?limit= er 1-100 (standard 50); send ?cursor= fra forrige side til cursor er null. Deling, oppheving av deling og tilbakestilling teller hver som én hendelse; å forlate gjør det ikke. Tilgang via en delt mappe lenger opp beholdes etter at du har forlatt elementet.
Feil
| Status | Når |
|---|---|
| 400 | Validering, manglende body, blandede opprettelsestyper |
| 401 | Manglende eller ugyldig bearer-nøkkel |
| 404 | Ukjent slug, domene eller mappe |
| 409 | Slug opptatt (code: "slug_taken") |
| 429 | Månedlig hendelseskvote nådd |
| 503 | API-nøkler er ikke konfigurert på denne deployeringen |
Se webhooks og egendefinerte domener for disse endepunktene.

