---
title: HTTP-API
description: >-
  REST unter https://api.linkdash.dev/v1 mit einem Bearer-Key aus dem Dashboard.
  Dieselben Operationen wie CLI und MCP.
sidebar:
  label: HTTP-API
  order: 4
---
Basis-URL: `https://api.linkdash.dev/v1`

Auth: `Authorization: Bearer ldash_...` (Keys erstellst du unter [Dashboard → API-Keys](https://linkdash.dev/dashboard/keys)). Erfinde keine Keys.

CLI-Referenz: [CLI](/de/cli). MCP: [MCP](/de/mcp). Preise / Kontingente: [Preise](/de/pricing). Discovery (ohne Auth): `GET https://api.linkdash.dev/v1`. Reines Markdown: [api.md](https://linkdash.dev/api.md).

Öffentliche IDs sind Slugs (`deck`, `k3m9xq`), nicht die Convex-`_id`. Die JSON-Feldnamen entsprechen der CLI-Ausgabe auf stdout (`id`, `url`, `kind`, …).

## Konventionen

- JSON `Content-Type: application/json`, sofern nicht anders angegeben.
- Beim Erstellen übergibst du genau eines von `url`, `text` oder `storageId` (nach `POST /uploads`), **oder** ein `variants`-Array (siehe [Varianten](#variants)), **oder** `"kind": "folder"` mit einem `name` (siehe [Ordner](#folders)). Der Mint-Aufruf gibt `{ "uploadUrl", "storageId" }` zurück. Der Host lädt die Bytes per PUT an `uploadUrl` hoch. Kleine Dateien können weiterhin multipart `file` an `POST /links` nutzen.
- Zeitangaben: `7d`, `24h`, `30m`, `1w` oder ein ISO-Datum. Felder: `expires` / `expiresAt`, `starts` / `startsAt`.
- Öffnungslimit: optionale positive Ganzzahl `maxOpenings`. Der Link pausiert nach so vielen erfolgreichen Öffnungen. Erhöhe `maxOpenings` oder nutze `clearMaxOpenings`, damit er wieder ausgeliefert wird. Lass `maxOpenings` weg für unbegrenzte Öffnungen.
- Wenn ein Slug auf zwei Domains des Owners existiert, übergib `?domain=` / JSON `domain`.
- Fehler: `{ "error": "..." }` plus optional `code`. Bereits vergebene `lida.sh`-Slugs liefern `409` mit `code: "slug_taken"`.
- Zugriff: Neue Links und Ordner sind `restricted`, sofern der Body nicht `access` setzt (siehe [Zugriff und Teilen](#access-and-sharing)). `url` in Antworten ist die Share-URL (`https://linkdash.dev/s/<token>`), außer der Link ist öffentlich – dann die Kurz-URL.
- Schreibvorgänge zählen zum monatlichen Event-Kontingent (inklusive Teilen, Teilen aufheben und Zurücksetzen). List / Get / Stats / Export / Shares-Liste / Shared / Webhook-List/Get zählen nicht. Aufrufe, Downloads und Wiedergaben zählen weiterhin.

## Endpunkte

| 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` (ohne 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` (ohne `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 nach dem 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` und `auth logout` sind Device-Flows im Browser. Sie sind keine Unkey-Routen.

## `GET /me`

Angemeldetes Konto. `{ "userId": "...", "email": "...", "name": "..." }`. E-Mail und Name fehlen, wenn sie unbekannt sind.

## URL-Link erstellen

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

Der JSON-Body nimmt genau eines von `url`, `text` oder `storageId`, dazu optional `access` (`restricted` als Standard \| `link` \| `public`), `slug`, `name`, `tags`, `starts`, `expires`, `maxOpenings`, `password`, `domain`, `previewName`, `previewDescription`, `previewImageStorageId`, `sticky`, `forwardParams`, `utm` (nur URL-Links) und `folder` (+ `folderDomain`), um den Link in einem Ordner zu erstellen. Die Kurzform erstellt eine Variante namens `main`; `password`, `starts`, `expires` und `maxOpenings` auf oberster Ebene bilden das Gate des Links. Antwort: `{ "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }`.

`GET /links` gibt eine Seite zurück, `{ "items": [...], "cursor" }`: `?limit=` liegt bei 1–100 (Standard 50); übergib `?cursor=` aus der vorherigen Seite, bis er `null` ist. `q` matcht ganze Wörter (das letzte als Präfix), sortiert nach Relevanz. Items sind `{ id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id }` (Ordnerzeilen haben zusätzlich `items`); der `kind`-Filter kennt zusätzlich `folder` und `group`, der `status`-Filter zusätzlich `mixed`, und `folder=<slug>|root` (+ `folderDomain`) listet einen Ordner oder die oberste Ebene. `GET /links/:id` gibt den vollständigen Link mit `access` und `variants` zurück; die Inhalte (`destinationUrl` / `textContent` / `fileName`) liegen auf der jeweiligen Variante.

## Datei hochladen

Erzeuge eine Upload-URL (`{uploadUrl,storageId}`), lade die Bytes vom Host per PUT hoch und erstelle dann im selben Ablauf den Link:

```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 Dateien können weiterhin Multipart an `POST /links` nutzen:

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

Optionale Multipart-Felder: `access`, `slug`, `name`, `tags`, `starts` / `startsAt`, `password`, `expires`, `maxOpenings`, `domain`, `previewName`, `previewDescription`, `previewImage`.

## Aktualisieren, Statistiken, CSV

`PATCH /links/:id` akzeptiert JSON oder Multipart. Ersetze die Datei-Bytes mit `storageId` nach `POST /uploads` + Host-PUT oder mit dem Multipart-Feld `file` (nur bei Links mit einer Variante). `--status` / `{ "status": "expired" }` wird abgelehnt – nutze `expires`. `{ "status": "scheduled" }` wird abgelehnt – nutze `starts`. Optional pausiert `maxOpenings` den Link nach so vielen Öffnungen; `clearMaxOpenings` entfernt das Limit. `sticky` (Boolean) und `restartSplit` (Boolean) steuern die Variantenzuweisung; `forwardParams` (Boolean) leitet den Query-String der Besucher weiter, siehe [Query-Parameter weiterleiten](#forward-query-parameters). `access` ändert, wer den Link öffnen kann; `resetShareLink: true` erzeugt eine neue Share-URL. Antwort: `{ "id", "url", "access", "status", "variantStatuses" }`.

`GET /links/:id/stats?last=24h` gibt `visits`, `downloads`, `plays`, `visitsInLast`, `countries`, `referrers`, `variants` (Summen pro Variante), `visitors` und `crawlers` zurück (`[{ "crawler", "company", "category", "hits", "lastSeen" }]`: Bots und Link-Vorschauen, die den Link abgerufen haben – sie zählen nie als Aufrufe; siehe [Crawler-Log](https://linkdash.dev/pricing.md)).

`GET /links/export` liefert CSV mit den Spalten `slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`, eine Zeile pro Variante (`folder` ist der Slug des übergeordneten Ordners; `access` ist `restricted`, `link` oder `public`). `POST /links/import` akzeptiert rohes CSV oder Multipart `file`; Zeilen werden nach Slug + Domain gruppiert (die erste Zeile erstellt den Link mit seiner Variante, weitere Zeilen fügen Varianten hinzu; bei bestehenden Links werden die Felder aktualisiert und dann Varianten anhand des Namens aktualisiert oder hinzugefügt). Zeilen mit `kind` `folder` (mit einem `name`) erstellen Ordner, und die Spalte `folder` ordnet Links erst zu, wenn alle Zeilen existieren. Ein leeres `access` macht neue Links `restricted` und lässt bestehende Links unverändert.

`DELETE /links/:id` auf einem Ordner nimmt `?contents=keep` (Standard: Items rücken eine Ebene nach oben) oder `?contents=delete` (Items und enthaltene Ordner werden ebenfalls gelöscht).

## Varianten

Jeder Link ist ein Container für eine oder mehrere **Varianten**: Inhalt (`url` | `file` | `text`) plus ein eigenes Gate (`password`, `paused`, `starts`, `expires`, `maxOpenings`), ein `weight` und optionale Besucherbedingungen `when`. Zum Link gehören Slug, Domain, Name, Tags, Vorschau, sein eigenes Gate (das Vorrang vor den Varianten-Gates hat), `sticky` (Standard `true`) und `splitVersion` (wird durch `restartSplit` erhöht). Ohne `variants` hat ein Link eine Variante namens `main`. Namen: Kleinbuchstaben, Ziffern, Bindestriche im Inneren, 1–40 Zeichen, eindeutig pro Link. Maximal 20 Varianten pro Link.

Ein Besucher bekommt genau eine Variante: Varianten, deren `when` zutrifft, bilden den Pool (trifft keine zu, bilden ihn die bedingungslosen Varianten), dann folgt eine gewichtete Auswahl (Sticky-Hash aus Besucher + Link + `splitVersion`, sonst zufällig). Crawler bekommen die erste aktive bedingungslose Variante. Der `kind` des Links ist `group` bei mehreren Varianten. Der `status` des Links ist das Link-Gate, falls gesetzt, sonst der Status, den alle Varianten teilen, sonst `mixed`. `variantStatuses` zählt `{ active, paused, expired, scheduled }`.

Mehrere Varianten auf einmal erstellen:

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

Jede Variante: `name` (Pflicht), eines von `url` | `text` | `storageId` (+ `fileName`, `fileType`, `fileSize`), `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when`. Beim Erstellen per Multipart gibt es nur die Kurzform.

| Route | Body | Antwort |
| --- | --- | --- |
| `GET /links/:id/variants` | — | Array der Varianten |
| `POST /links/:id/variants` | JSON oder Multipart `file`: `name` (Pflicht), Inhalt, `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when` | die Variante |
| `PATCH /links/:id/variants/:name` | `name` (umbenennen), `url`, `text`, `storageId` / `file`, `password`, `clearPassword`, `starts`, `clearStarts`, `expires`, `clearExpires`, `maxOpenings`, `clearMaxOpenings`, `status` (`active` \| `paused`), `weight`, `when`, `clearWhen`, `utm` | die Variante |
| `DELETE /links/:id/variants/:name` | — | `{ "id", "variant", "deleted": true }` (die letzte Variante kann nicht gelöscht werden) |

`when`-Keys (String-Arrays; jeder gesetzte Key muss zutreffen): `countries` (ISO-2), `devices` (`mobile` | `tablet` | `desktop`), `os` (`windows` | `macos` | `android` | `ios` | `linux` | `other`), `browsers` (`edge` | `chrome` | `firefox` | `safari` | `other`), `languages` (Präfix), `referrerHosts` (Host-Suffix).

### Regeln für Query-Parameter

`when.params` ist ein Array mit bis zu 10 Regeln für den Query-String des Besuchers (`lida.sh/promo?src=newsletter`); jede Regel muss erfüllt sein. Jede Regel ist `{ "key", "op", "value" }`, wobei `op` eines von `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` ist eine durch `|` oder Komma getrennte Liste) | `exists` | `missing` ist. `value` ist Pflicht, außer bei `exists` / `missing`. Keys unterscheiden Groß- und Kleinschreibung, Werte werden exakt verglichen.

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

Parameterwerte werden beim Öffnen abgeglichen und nie in den Analytics gespeichert.

### Query-Parameter weiterleiten

`forwardParams` (Boolean am Link, Standard `false`; setzbar bei `POST /links` und `PATCH /links/:id`, zurückgegeben von `GET /links/:id`) hängt den kompletten Query-String des Besuchers an URL-Varianten an. Werte des Besuchers überschreiben gespeicherte Werte, `utm` eingeschlossen. Datei- und Textvarianten ignorieren das. Das ist Routing, keine Zugriffskontrolle: Jeder kann Parameter anhängen. Parameterwerte werden nicht in den Analytics gespeichert.

## Ordner

Ein Ordner ist ein Link, der die Items auflistet, die du hineinlegst. Das Modell findest du unter [Ordner](/de/folders).

```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 | Antwort |
| --- | --- | --- |
| `POST /links` | `{ "kind": "folder", "name" }` plus die üblichen Link-Felder; kein `url`, `text`, `storageId` oder `variants` | der erstellte Ordner |
| `POST /links/:id/move` | `{ "folder": "<slug>" }` oder `{ "folder": null }` für die oberste Ebene, optional `folderDomain` | `{ "id", "folder" }` |
| `POST /links/:id/copy` | — | `{ "id", "url", "access", "kind", "variants", "folder", … }` (gleicher Zugriff, neue Share-URL, keine Personen) |

Verschieben und Kopieren zählen jeweils als ein Event. Ein unbekannter Ordner-Slug liefert `404` (`Folder "<slug>" not found`); ein Slug, der kein Ordner ist, oder das Verschieben eines Ordners in sich selbst oder einen darunterliegenden Ordner liefert `400`. Ordner lassen sich höchstens 32 Ebenen tief verschachteln.

## Zugriff und Teilen

Jeder Link und jeder Ordner hat `access`: `restricted` (Standard; der Owner und Personen, mit denen geteilt wurde, angemeldet, unter `https://linkdash.dev/s/<token>`), `link` (jeder mit dieser URL) oder `public` (jeder, unter der Kurz-URL). Setze es bei `POST /links` oder `PATCH /links/:id`. Übergib `"access": "public"` für Links, die öffentlich gepostet werden sollen. Wie Ordner und Viewer funktionieren, erfährst du unter [Teilen und Zugriff](/de/sharing).

```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 | Antwort |
| --- | --- | --- |
| `POST /links/:id/shares` | `{ "emails": [...] }` (1–50 E-Mails) | `{ "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, was du geteilt hast) |
| `GET /shared` | — | `{ "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }` |
| `DELETE /shared/:id` | — | `{ "_id", "left": true }` (`:id` ist die `_id` oder der Share-Token aus `GET /shared`) |
| `POST /links/:id/reset-link` | — | `{ "id", "access", "url" }` |

`POST /links/:id/shares` nimmt `"role": "editor"` für Editoren. Editoren können Items ändern und Statistiken sowie Aktivität sehen, aber nie Passwörter, Slug, Domain, Zugriff, Teilen, Löschen, Verschieben oder Kopieren (`403`); sie verwenden die `_id` oder den Share-Token des Items als `:id`, und eine passwortgeschützte Variante bleibt `locked: true`, bis `POST /links/:id/unlock` aufgerufen wird (30 Minuten, zehn falsche Passwörter pro Stunde, danach `429`). Speichern, nachdem jemand anderes gespeichert hat, ergibt nur dann `409`, wenn der Request `expectedVersion` mitsendet. Alle Share-Routen nehmen `?domain=`, wenn sich der Slug wiederholt. `accepted` ist `false`, bis diese E-Mail-Adresse ein verifiziertes Konto hat; `viaFolder` bedeutet, dass der Zugriff von einem übergeordneten Ordner kommt. Bis zu 200 Personen pro Item und 100 Einladungs-E-Mails pro Konto und Tag. `GET /shares` und `GET /shared` liefern jeweils eine Seite: `?limit=` liegt bei 1–100 (Standard 50); übergib `?cursor=` aus der vorherigen Seite, bis `cursor` `null` ist. Teilen, Teilen aufheben und Zurücksetzen zählen jeweils als ein Event; Verlassen nicht. Zugriff über einen geteilten übergeordneten Ordner bleibt nach dem Verlassen bestehen.

## Fehler

| Status | Wann |
| --- | --- |
| 400 | Validierung, fehlender Body, gemischte Erstellungsarten |
| 401 | Fehlender oder ungültiger Bearer-Key |
| 404 | Unbekannter Slug, unbekannte Domain oder unbekannter Ordner |
| 409 | Slug bereits vergeben (`code: "slug_taken"`) |
| 429 | Monatliches Event-Kontingent erreicht |
| 503 | API-Keys sind auf diesem Deployment nicht konfiguriert |

Die zugehörigen Endpunkte findest du unter [Webhooks](/de/webhooks) und [Custom Domains](/de/domains).
