HTTP-API
REST unter https://api.linkdash.dev/v1 mit einem Bearer-Key aus dem Dashboard. Dieselben Operationen wie CLI und MCP.
Basis-URL: https://api.linkdash.dev/v1
Auth: Authorization: Bearer ldash_... (Keys erstellst du unter Dashboard → API-Keys). Erfinde keine Keys.
CLI-Referenz: CLI. MCP: MCP. Preise / Kontingente: Preise. Discovery (ohne Auth): GET https://api.linkdash.dev/v1. Reines Markdown: 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,textoderstorageId(nachPOST /uploads), oder einvariants-Array (siehe Varianten), oder"kind": "folder"mit einemname(siehe Ordner). Der Mint-Aufruf gibt{ "uploadUrl", "storageId" }zurück. Der Host lädt die Bytes per PUT anuploadUrlhoch. Kleine Dateien können weiterhin multipartfileanPOST /linksnutzen. - Zeitangaben:
7d,24h,30m,1woder ein ISO-Datum. Felder:expires/expiresAt,starts/startsAt. - Öffnungslimit: optionale positive Ganzzahl
maxOpenings. Der Link pausiert nach so vielen erfolgreichen Öffnungen. ErhöhemaxOpeningsoder nutzeclearMaxOpenings, damit er wieder ausgeliefert wird. LassmaxOpeningsweg für unbegrenzte Öffnungen. - Wenn ein Slug auf zwei Domains des Owners existiert, übergib
?domain=/ JSONdomain. - Fehler:
{ "error": "..." }plus optionalcode. Bereits vergebenelida.sh-Slugs liefern409mitcode: "slug_taken". - Zugriff: Neue Links und Ordner sind
restricted, sofern der Body nichtaccesssetzt (siehe Zugriff und Teilen).urlin 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" } |
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
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:
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:
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. 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).
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:
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.
{ "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.
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.
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 und Custom Domains.

