Zum Inhalt springen
LinkdashLinkdash
Deutsch
Esc
↑↓navigieren↵öffnen⌘Jvorschau
Auf dieser Seite

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, text oder storageId (nach POST /uploads), oder ein variants-Array (siehe Varianten), oder "kind": "folder" mit einem name (siehe Ordner). 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). 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" }
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.

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.

War diese Seite hilfreich?