HTTP API
REST op https://api.linkdash.dev/v1 met een bearer-key uit het dashboard. Dezelfde bewerkingen als de CLI en MCP.
Basis-URL: https://api.linkdash.dev/v1
Auth: Authorization: Bearer ldash_... (maak keys aan via Dashboard → API-keys). Verzin geen keys.
CLI-referentie: CLI. MCP: MCP. Prijzen / quota: Prijzen. Discovery (zonder auth): GET https://api.linkdash.dev/v1. Platte markdown: api.md.
Publieke id’s zijn slugs (deck, k3m9xq), geen Convex-_id. JSON-veldnamen komen overeen met de stdout van de CLI (id, url, kind, …).
Conventies
- JSON
Content-Type: application/json, tenzij anders vermeld. - Create accepteert precies één van
url,textofstorageIdnaPOST /uploads, of eenvariants-array (zie Varianten), of"kind": "folder"met eenname(zie Mappen). Mint geeft{ "uploadUrl", "storageId" }terug. De host PUT de bytes naaruploadUrl. Kleine bestanden mogen nog steeds multipartfileopPOST /linksgebruiken. - Duur:
7d,24h,30m,1wof een ISO-datum. Velden:expires/expiresAt,starts/startsAt. - Limiet op openingen: optioneel positief geheel getal
maxOpenings. De link wordt gepauzeerd na dat aantal geslaagde openingen. VerhoogmaxOpeningsof gebruikclearMaxOpeningsom hem weer te serveren. LaatmaxOpeningsweg voor onbeperkt. - Bestaat een slug op twee domeinen van de eigenaar, geef dan
?domain=/ JSONdomainmee. - Fouten:
{ "error": "..." }plus optioneelcode. Bezettelida.sh-slugs geven409terug metcode: "slug_taken". - Toegang: nieuwe links en mappen zijn
restricted, tenzij de bodyaccessinstelt (zie Toegang en delen).urlin responses is de deel-URL (https://linkdash.dev/s/<token>), tenzij de link publiek is, dan is het de korte URL. - Schrijfacties tellen mee voor het maandelijkse event-quotum (delen, delen intrekken en reset inbegrepen). List / get / stats / export / shares list / shared / webhook list/get tellen niet mee. Ingest van bezoeken / downloads / afspelen telt nog steeds mee.
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 (zonder 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 (zonder 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 na 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 en auth logout zijn device flows in de browser. Het zijn geen Unkey-routes.
GET /me
Het ingelogde account. { "userId": "...", "email": "...", "name": "..." }. E-mail en naam worden weggelaten als ze onbekend zijn.
Een URL-link aanmaken
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"}'
De JSON-body accepteert precies één van url, text of storageId, plus optioneel access (restricted standaard | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (alleen URL-links) en folder (+ folderDomain) om de link in een map aan te maken. De verkorte vorm maakt één variant met de naam main; password, starts, expires en maxOpenings op het hoogste niveau vormen de gate van de link. Response: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.
GET /links geeft één pagina terug, { "items": [...], "cursor" }: ?limit= is 1-100 (standaard 50); geef ?cursor= van de vorige pagina mee tot die null is. q matcht hele woorden (het laatste als prefix), gesorteerd op relevantie. Items zijn { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (maprijen voegen items toe); het kind-filter voegt folder en group toe, het status-filter voegt mixed toe, en folder=<slug>|root (+ folderDomain) toont één map of het hoogste niveau. GET /links/:id geeft de volledige link terug met access en variants; de inhoud (destinationUrl / textContent / fileName) staat op elke variant.
Een bestand uploaden
Mint een upload-URL ({uploadUrl,storageId}), PUT de bytes vanaf de host en maak daarna in dezelfde flow de link aan:
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}'
Kleine bestanden kunnen nog steeds multipart gebruiken op POST /links:
curl https://api.linkdash.dev/v1/links \
-H "Authorization: Bearer ldash_..." \
-F "file=@./deck.pdf" \
-F "expires=7d" \
-F "slug=deck"
Optionele multipart-velden: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.
Bijwerken, statistieken, CSV
PATCH /links/:id is JSON of multipart. Vervang de bytes van een bestand met storageId na POST /uploads + host-PUT, of met het multipart-veld file (alleen links met één variant). --status / { "status": "expired" } wordt geweigerd — gebruik expires. { "status": "scheduled" } wordt geweigerd — gebruik starts. Met het optionele maxOpenings pauzeer je de link na dat aantal openingen; clearMaxOpenings haalt de limiet weg. sticky (boolean) en restartSplit (boolean) bepalen de toewijzing van varianten; forwardParams (boolean) stuurt de querystring van de bezoeker door, zie Queryparameters doorsturen. access bepaalt wie de link kan openen; resetShareLink: true geeft een nieuwe deel-URL uit. Response: { "id", "url", "access", "status", "variantStatuses" }.
GET /links/:id/stats?last=24h geeft visits, downloads, plays, visitsInLast, countries, referrers, variants (totalen per variant), visitors en crawlers terug ([{ "crawler", "company", "category", "hits", "lastSeen" }]: bots en linkpreviews die de link hebben opgehaald, nooit als bezoek geteld; zie Crawler-log).
GET /links/export is CSV met de kolommen slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, één rij per variant (folder is de slug van de bovenliggende map; access is restricted, link of public). POST /links/import accepteert ruwe CSV of multipart file; rijen worden gegroepeerd op slug + domein (de eerste rij maakt de link aan met zijn variant, volgende rijen voegen varianten toe; bij bestaande links worden velden bijgewerkt en daarna varianten op naam bijgewerkt of toegevoegd). Rijen met kind folder (met een name) maken mappen aan, en de kolom folder plaatst links pas nadat alle rijen bestaan. Een lege access maakt nieuwe links restricted en laat bestaande links zoals ze zijn.
DELETE /links/:id op een map accepteert ?contents=keep (standaard: items gaan een niveau omhoog) of ?contents=delete (items en mappen erin worden ook verwijderd).
Varianten
Elke link is een container met een of meer varianten: inhoud (url | file | text) plus een eigen gate (password, paused, starts, expires, maxOpenings), een weight en optionele bezoekersvoorwaarden when. De link bezit slug, domein, naam, tags, preview, een eigen gate (die voorgaat op de gates van varianten), sticky (standaard true) en splitVersion (opgehoogd door restartSplit). Zonder variants heeft een link één variant met de naam main. Namen: kleine letters, cijfers, koppeltekens binnenin, 1–40 tekens, uniek per link. Maximaal 20 varianten per link.
Een bezoeker krijgt één variant: varianten waarvan when matcht vormen de pool (matcht er geen, dan doen de onvoorwaardelijke varianten dat), daarna volgt een gewogen keuze (sticky hash van bezoeker + link + splitVersion, anders willekeurig). Crawlers krijgen de eerste live onvoorwaardelijke variant. De kind van een link is group bij meerdere varianten. De status van een link is de gate van de link als die is ingesteld, anders de status die alle varianten delen, anders mixed. variantStatuses telt { active, paused, expired, scheduled }.
Maak meerdere varianten tegelijk aan:
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"]}}]}'
Elke variant: name (verplicht), één van url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. Multipart-create blijft alleen de verkorte vorm.
| Route | Body | Response |
|---|---|---|
GET /links/:id/variants |
— | array met varianten |
POST /links/:id/variants |
JSON of multipart file: name (verplicht), inhoud, password, starts, expires, maxOpenings, utm, weight, when |
de variant |
PATCH /links/:id/variants/:name |
name (hernoemen), url, text, storageId / file, password, clearPassword, starts, clearStarts, expires, clearExpires, maxOpenings, clearMaxOpenings, status (active | paused), weight, when, clearWhen, utm |
de variant |
DELETE /links/:id/variants/:name |
— | { "id", "variant", "deleted": true } (de laatste variant kan niet worden verwijderd) |
when-keys (arrays van strings; elke ingestelde key moet matchen): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (prefix), referrerHosts (host-suffix).
Regels voor queryparameters
when.params is een array van maximaal 10 regels op de querystring van de bezoeker (lida.sh/promo?src=newsletter); elke regel moet kloppen. Elke regel is { "key", "op", "value" } met op een van equals | notEquals | includes | startsWith | endsWith | in (value is een lijst gescheiden door | of komma’s) | exists | missing. value is verplicht, behalve bij exists / missing. Keys zijn hoofdlettergevoelig, waarden worden exact vergeleken.
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
Parameterwaarden worden gematcht op het moment van openen en nooit opgeslagen in analytics.
Queryparameters doorsturen
forwardParams (boolean op de link, standaard false; in te stellen op POST /links en PATCH /links/:id, teruggegeven door GET /links/:id) plakt de volledige querystring van de bezoeker achter URL-varianten. Waarden van de bezoeker overschrijven opgeslagen waarden, utm inbegrepen. Bestands- en tekstvarianten negeren het. Dit is routering, geen toegangscontrole: iedereen kan parameters toevoegen. Parameterwaarden worden niet opgeslagen in analytics.
Mappen
Een map is een link die de items toont die je erin zet. Zie Mappen voor het model.
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 | Response |
|---|---|---|
POST /links |
{ "kind": "folder", "name" } plus de gebruikelijke linkvelden; geen url, text, storageId of variants |
de aangemaakte map |
POST /links/:id/move |
{ "folder": "<slug>" } of { "folder": null } voor het hoogste niveau, optioneel folderDomain |
{ "id", "folder" } |
POST /links/:id/copy |
— | { "id", "url", "access", "kind", "variants", "folder", … } (zelfde toegang, nieuwe deel-URL, geen personen) |
Verplaatsen en kopiëren tellen elk als één event. Een onbekende map-slug geeft 404 terug (Folder "<slug>" not found); een slug die geen map is, of een map in zichzelf of in een onderliggende map verplaatsen, geeft 400 terug. Mappen kunnen maximaal 32 niveaus diep genest worden.
Toegang en delen
Elke link en map heeft access: restricted (standaard; de eigenaar en de mensen met wie hij gedeeld is, ingelogd, op https://linkdash.dev/s/<token>), link (iedereen met die URL) of public (iedereen, op de korte URL). Stel het in op POST /links of PATCH /links/:id. Geef "access": "public" mee voor links die publiek gepost gaan worden. Zie Delen en toegang voor hoe mappen en kijkers werken.
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 | Response |
|---|---|---|
POST /links/:id/shares |
{ "emails": [...] } (1–50 e-mailadressen) |
{ "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" } (alles wat jij hebt gedeeld) |
GET /shared |
— | { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" } |
DELETE /shared/:id |
— | { "_id", "left": true } (:id is de _id of het deeltoken uit GET /shared) |
POST /links/:id/reset-link |
— | { "id", "access", "url" } |
POST /links/:id/shares accepteert "role": "editor" voor editors. Editors kunnen items wijzigen en zien statistieken en activiteit, maar nooit wachtwoorden, slug, domein, toegang, delen, verwijderen, verplaatsen of kopiëren (403); ze gebruiken de _id of het deeltoken van het item als :id, en een met een wachtwoord beveiligde variant blijft locked: true tot POST /links/:id/unlock (30 minuten, tien foute wachtwoorden per uur, daarna 429). Opslaan nadat iemand anders heeft opgeslagen geeft alleen 409 als het request expectedVersion meestuurt. Alle deelroutes accepteren ?domain= als de slug vaker voorkomt. accepted is false tot dat e-mailadres een geverifieerd account heeft; viaFolder betekent dat de toegang van een bovenliggende map komt. Maximaal 200 personen per item en 100 uitnodigingsmails per account per dag. GET /shares en GET /shared geven telkens één pagina terug: ?limit= is 1-100 (standaard 50); geef ?cursor= van de vorige pagina mee tot cursor null is. Delen, delen intrekken en reset tellen elk als één event; verlaten niet. Toegang via een gedeelde bovenliggende map blijft na het verlaten bestaan.
Fouten
| Status | Wanneer |
|---|---|
| 400 | Validatie, ontbrekende body, gemengde create-soorten |
| 401 | Ontbrekende of ongeldige bearer-key |
| 404 | Onbekende slug, domein of map |
| 409 | Slug bezet (code: "slug_taken") |
| 429 | Maandelijks event-quotum bereikt |
| 503 | API-keys niet geconfigureerd op deze deployment |
Zie webhooks en eigen domeinen voor die endpoints.

