---
title: HTTP API
description: >-
  REST op https://api.linkdash.dev/v1 met een bearer-key uit het dashboard.
  Dezelfde bewerkingen als de CLI en MCP.
sidebar:
  label: HTTP API
  order: 4
---
Basis-URL: `https://api.linkdash.dev/v1`

Auth: `Authorization: Bearer ldash_...` (maak keys aan via [Dashboard → API-keys](https://linkdash.dev/dashboard/keys)). Verzin geen keys.

CLI-referentie: [CLI](/nl/cli). MCP: [MCP](/nl/mcp). Prijzen / quota: [Prijzen](/nl/pricing). Discovery (zonder auth): `GET https://api.linkdash.dev/v1`. Platte markdown: [api.md](https://linkdash.dev/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](#variants)), **of** `"kind": "folder"` met een `name` (zie [Mappen](#folders)). 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](#access-and-sharing)). `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" }` | `{ "id", "email", "role" }` |
| `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

```bash
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:

```bash
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`:

```bash
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](#forward-query-parameters). `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](https://linkdash.dev/pricing.md)).

`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:

```bash
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.

```json
{ "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](/nl/folders) voor het model.

```bash
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](/nl/sharing) voor hoe mappen en kijkers werken.

```bash
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](/nl/webhooks) en [eigen domeinen](/nl/domains) voor die endpoints.
