---
title: HTTP API
description: >-
  REST på https://api.linkdash.dev/v1 med en bearer-nyckel från dashboarden.
  Samma operationer som CLI:n och MCP.
sidebar:
  label: HTTP API
  order: 4
---
Bas-URL: `https://api.linkdash.dev/v1`

Autentisering: `Authorization: Bearer ldash_...` (skapa nycklar under [Dashboard → API-nycklar](https://linkdash.dev/dashboard/keys)). Hitta inte på nycklar.

CLI-referens: [CLI](/sv/cli). MCP: [MCP](/sv/mcp). Priser / kvoter: [Priser](/sv/pricing). Discovery (ingen autentisering): `GET https://api.linkdash.dev/v1`. Ren markdown: [api.md](https://linkdash.dev/api.md).

Publika id:n är slugs (`deck`, `k3m9xq`), inte Convex `_id`. JSON-fältnamnen matchar CLI:ns stdout (`id`, `url`, `kind`, …).

## Konventioner

- JSON `Content-Type: application/json` om inget annat anges.
- Create tar exakt ett av `url`, `text` eller `storageId` efter `POST /uploads`, **eller** en `variants`-array (se [Varianter](#variants)), **eller** `"kind": "folder"` med ett `name` (se [Mappar](#folders)). Mint returnerar `{ "uploadUrl", "storageId" }`. Hosten skickar byten med PUT till `uploadUrl`. Små filer kan fortfarande använda multipart `file` på `POST /links`.
- Varaktigheter: `7d`, `24h`, `30m`, `1w` eller ett ISO-datum. Fält: `expires` / `expiresAt`, `starts` / `startsAt`.
- Öppningsgräns: valfritt positivt heltal `maxOpenings`. Länken pausas efter så många lyckade öppningar. Höj `maxOpenings`, eller använd `clearMaxOpenings`, för att servera den igen. Utelämna `maxOpenings` för obegränsat.
- Om en slug finns på två av ägarens domäner skickar du `?domain=` / JSON `domain`.
- Fel: `{ "error": "..." }` plus valfri `code`. Upptagna `lida.sh`-slugs returnerar `409` med `code: "slug_taken"`.
- Åtkomst: nya länkar och mappar är `restricted` om inte bodyn sätter `access` (se [Åtkomst och delning](#access-and-sharing)). `url` i svaren är delnings-URL:en (`https://linkdash.dev/s/<token>`) om inte länken är publik, då är det den korta URL:en.
- Skrivningar räknas mot den månatliga eventkvoten (delning, borttagen delning och återställning inräknade). List / get / stats / export / shares list / shared / webhook list/get räknas inte. Besök / nedladdningar / uppspelningar räknas fortfarande.

## 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` (utan 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` (utan `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 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` och `auth logout` är device flows i webbläsaren. De är inte Unkey-routes.

## `GET /me`

Inloggat konto. `{ "userId": "...", "email": "...", "name": "..." }`. E-post och namn utelämnas när de är okända.

## Skapa en URL-länk

```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"}'
```

JSON-bodyn tar exakt ett av `url`, `text` eller `storageId`, plus valfria `access` (`restricted` som standard \| `link` \| `public`), `slug`, `name`, `tags`, `starts`, `expires`, `maxOpenings`, `password`, `domain`, `previewName`, `previewDescription`, `previewImageStorageId`, `sticky`, `forwardParams`, `utm` (bara URL-länkar) och `folder` (+ `folderDomain`) för att skapa länken i en mapp. Kortformen skapar en variant som heter `main`; `password`, `starts`, `expires` och `maxOpenings` på toppnivå är länkens spärr. Svar: `{ "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }`.

`GET /links` returnerar en sida, `{ "items": [...], "cursor" }`: `?limit=` är 1-100 (standard 50); skicka `?cursor=` från föregående sida tills den är `null`. `q` matchar hela ord (det sista som prefix), rankat efter relevans. Posterna är `{ id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id }` (mapprader lägger till `items`); `kind`-filtret lägger till `folder` och `group`, `status`-filtret lägger till `mixed`, och `folder=<slug>|root` (+ `folderDomain`) listar en mapp eller toppnivån. `GET /links/:id` returnerar hela länken med `access` och `variants`; innehållet (`destinationUrl` / `textContent` / `fileName`) ligger på varje variant.

## Ladda upp en fil

Minta en uppladdnings-URL (`{uploadUrl,storageId}`), skicka byten med PUT från hosten och skapa sedan länken i samma flöde:

```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}'
```

Små filer kan fortfarande använda multipart på `POST /links`:

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -F "file=@./deck.pdf" \
  -F "expires=7d" \
  -F "slug=deck"
```

Valfria multipart-fält: `access`, `slug`, `name`, `tags`, `starts` / `startsAt`, `password`, `expires`, `maxOpenings`, `domain`, `previewName`, `previewDescription`, `previewImage`.

## Uppdatering, statistik, CSV

`PATCH /links/:id` tar JSON eller multipart. Byt ut filens bytes med `storageId` efter `POST /uploads` + host-PUT, eller med multipart-fältet `file` (bara länkar med en enda variant). `--status` / `{ "status": "expired" }` avvisas – använd `expires`. `{ "status": "scheduled" }` avvisas – använd `starts`. Valfri `maxOpenings` pausar länken efter så många öppningar; `clearMaxOpenings` tar bort gränsen. `sticky` (boolean) och `restartSplit` (boolean) styr hur varianter tilldelas; `forwardParams` (boolean) vidarebefordrar besökarens query string, se [Vidarebefordra query-parametrar](#forward-query-parameters). `access` ändrar vem som kan öppna den; `resetShareLink: true` ger en ny delnings-URL. Svar: `{ "id", "url", "access", "status", "variantStatuses" }`.

`GET /links/:id/stats?last=24h` returnerar `visits`, `downloads`, `plays`, `visitsInLast`, `countries`, `referrers`, `variants` (totaler per variant), `visitors` och `crawlers` (`[{ "crawler", "company", "category", "hits", "lastSeen" }]`: botar och länkförhandsvisningar som har hämtat länken, räknas aldrig som besök; se [Crawlerlogg](https://linkdash.dev/pricing.md)).

`GET /links/export` är CSV med kolumnerna `slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`, en rad per variant (`folder` är slugen för mappen som innehåller länken; `access` är `restricted`, `link` eller `public`). `POST /links/import` tar emot rå CSV eller multipart `file`; rader grupperas efter slug + domän (första raden skapar länken med sin variant, fler rader lägger till varianter; befintliga länkar får sina fält uppdaterade, sedan uppdateras eller läggs varianter till efter namn). Rader med `kind` `folder` (med ett `name`) skapar mappar, och kolumnen `folder` placerar länkarna när alla rader finns. En tom `access` gör nya länkar begränsade och lämnar befintliga länkar som de är.

`DELETE /links/:id` på en mapp tar `?contents=keep` (standard: posterna flyttas upp en nivå) eller `?contents=delete` (poster och mappar i den raderas också).

## Varianter

Varje länk är en behållare för en eller flera **varianter**: innehåll (`url` | `file` | `text`) plus en egen spärr (`password`, `paused`, `starts`, `expires`, `maxOpenings`), en `weight` och valfria besökarvillkor `when`. Länken äger slug, domän, namn, taggar, förhandsvisning, sin egen spärr (som går före variantspärrarna), `sticky` (standard `true`) och `splitVersion` (räknas upp av `restartSplit`). Utan `variants` har en länk en variant som heter `main`. Namn: gemener, siffror, bindestreck inuti, 1–40 tecken, unika per länk. Max 20 varianter per länk.

En besökare får en variant: varianter vars `when` matchar bildar poolen (om ingen matchar gör de villkorslösa varianterna det), sedan görs ett viktat val (sticky hash av besökare + länk + `splitVersion`, annars slumpmässigt). Crawlers får den första aktiva villkorslösa varianten. Länkens `kind` är `group` när den har flera varianter. Länkens `status` är länkspärren när den är satt, annars den status som alla varianter delar, annars `mixed`. `variantStatuses` räknar `{ active, paused, expired, scheduled }`.

Skapa flera varianter på en gång:

```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"]}}]}'
```

Varje variant: `name` (obligatoriskt), ett av `url` | `text` | `storageId` (+ `fileName`, `fileType`, `fileSize`), `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when`. Create via multipart stöder bara kortformen.

| Route | Body | Svar |
| --- | --- | --- |
| `GET /links/:id/variants` | — | array med varianter |
| `POST /links/:id/variants` | JSON eller multipart `file`: `name` (obligatoriskt), innehåll, `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when` | varianten |
| `PATCH /links/:id/variants/:name` | `name` (byt namn), `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 sista varianten kan inte raderas) |

`when`-nycklar (arrayer av strängar; varje nyckel som är satt måste matcha): `countries` (ISO-2), `devices` (`mobile` | `tablet` | `desktop`), `os` (`windows` | `macos` | `android` | `ios` | `linux` | `other`), `browsers` (`edge` | `chrome` | `firefox` | `safari` | `other`), `languages` (prefix), `referrerHosts` (värdsuffix).

### Regler för query-parametrar

`when.params` är en array med upp till 10 regler för besökarens query string (`lida.sh/promo?src=newsletter`); alla regler måste gälla. Varje regel är `{ "key", "op", "value" }` där `op` är ett av `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` är en lista separerad med `|` eller komma) | `exists` | `missing`. `value` krävs utom för `exists` / `missing`. Nycklar är skiftlägeskänsliga och värden jämförs exakt.

```json
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
```

Parametervärden matchas när länken öppnas och lagras aldrig i analysdatan.

### Vidarebefordra query-parametrar

`forwardParams` (boolean på länken, standard `false`; kan sättas på `POST /links` och `PATCH /links/:id`, returneras av `GET /links/:id`) lägger till besökarens hela query string på URL-varianter. Besökarens värden skriver över de lagrade, `utm` inräknat. Fil- och textvarianter ignorerar den. Det här är routing, inte åtkomstkontroll: vem som helst kan lägga till parametrar. Parametervärden lagras inte i analysdatan.

## Mappar

En mapp är en länk som listar posterna du lägger i den. Se [Mappar](/sv/folders) för hur modellen fungerar.

```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 | Svar |
| --- | --- | --- |
| `POST /links` | `{ "kind": "folder", "name" }` plus de vanliga länkfälten; ingen `url`, `text`, `storageId` eller `variants` | den skapade mappen |
| `POST /links/:id/move` | `{ "folder": "<slug>" }` eller `{ "folder": null }` för toppnivån, valfri `folderDomain` | `{ "id", "folder" }` |
| `POST /links/:id/copy` | — | `{ "id", "url", "access", "kind", "variants", "folder", … }` (samma åtkomst, ny delnings-URL, inga personer) |

Flytt och kopiering räknas som ett event var. En okänd mapp-slug returnerar `404` (`Folder "<slug>" not found`); en slug som inte är en mapp, eller att flytta en mapp in i sig själv eller i en mapp under den, returnerar `400`. Mappar kan nästlas högst 32 nivåer djupt.

## Åtkomst och delning

Varje länk och mapp har `access`: `restricted` (standard; ägaren och de personer den delats med, inloggade, på `https://linkdash.dev/s/<token>`), `link` (vem som helst med den URL:en) eller `public` (vem som helst, på den korta URL:en). Sätt den på `POST /links` eller `PATCH /links/:id`. Skicka `"access": "public"` för länkar som ska publiceras offentligt. Se [Delning och åtkomst](/sv/sharing) för hur mappar och tittare fungerar.

```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 | 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" }` (allt du har delat) |
| `GET /shared` | — | `{ "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }` |
| `DELETE /shared/:id` | — | `{ "_id", "left": true }` (`:id` är `_id` eller delningstoken från `GET /shared`) |
| `POST /links/:id/reset-link` | — | `{ "id", "access", "url" }` |

`POST /links/:id/shares` tar `"role": "editor"` för redaktörer. Redaktörer kan ändra poster och se statistik och aktivitet, men aldrig lösenord, slug, domän, åtkomst, delning, radering, flytt eller kopiering (`403`). De använder postens `_id` eller delningstoken som `:id`, och en lösenordsskyddad variant förblir `locked: true` tills `POST /links/:id/unlock` (30 minuter, tio felaktiga lösenord per timme, sedan `429`). Att spara efter att någon annan har sparat ger `409` bara när requesten skickar `expectedVersion`. Alla delningsroutes tar `?domain=` när slugen förekommer på flera domäner. `accepted` är `false` tills den e-postadressen har ett verifierat konto; `viaFolder` betyder att åtkomsten kommer från en mapp längre upp. Upp till 200 personer per post och 100 inbjudningsmejl per konto och dag. `GET /shares` och `GET /shared` returnerar en sida i taget: `?limit=` är 1-100 (standard 50); skicka `?cursor=` från föregående sida tills `cursor` är `null`. Delning, borttagen delning och återställning räknas som ett event var; att lämna räknas inte. Åtkomst via en delad mapp längre upp finns kvar efter att du har lämnat.

## Fel

| Status | När |
| --- | --- |
| 400 | Validering, saknad body, blandade create-typer |
| 401 | Saknad eller ogiltig bearer-nyckel |
| 404 | Okänd slug, domän eller mapp |
| 409 | Slugen är upptagen (`code: "slug_taken"`) |
| 429 | Den månatliga eventkvoten är nådd |
| 503 | API-nycklar är inte konfigurerade i den här driftsättningen |

Se [webhooks](/sv/webhooks) och [egna domäner](/sv/domains) för de endpoints som hör dit.
