Naar inhoud springen
LinkdashLinkdash
Nederlands
Esc
↑↓navigeren↵openen⌘Jvoorbeeld
Op deze pagina

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, text of storageId na POST /uploads, of een variants-array (zie Varianten), of "kind": "folder" met een name (zie Mappen). Mint geeft { "uploadUrl", "storageId" } terug. De host PUT de bytes naar uploadUrl. Kleine bestanden mogen nog steeds multipart file op POST /links gebruiken.
  • Duur: 7d, 24h, 30m, 1w of 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. Verhoog maxOpenings of gebruik clearMaxOpenings om hem weer te serveren. Laat maxOpenings weg voor onbeperkt.
  • Bestaat een slug op twee domeinen van de eigenaar, geef dan ?domain= / JSON domain mee.
  • Fouten: { "error": "..." } plus optioneel code. Bezette lida.sh-slugs geven 409 terug met code: "slug_taken".
  • Toegang: nieuwe links en mappen zijn restricted, tenzij de body access instelt (zie Toegang en delen). url in 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.

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.

Was deze pagina nuttig?