API HTTP
REST su https://api.linkdash.dev/v1 con una chiave bearer creata dalla dashboard. Offre le stesse operazioni della CLI e dell'MCP.
URL di base: https://api.linkdash.dev/v1
Autenticazione: Authorization: Bearer ldash_... (crea le chiavi in Dashboard → Chiavi API). Non inventare chiavi.
Riferimento CLI: CLI. MCP: MCP. Prezzi / quote: Prezzi. Discovery (senza autenticazione): GET https://api.linkdash.dev/v1. Markdown semplice: api.md.
Gli id pubblici sono slug (deck, k3m9xq), non _id di Convex. I nomi dei campi JSON sono gli stessi dello stdout della CLI (id, url, kind, …).
Convenzioni
- JSON con
Content-Type: application/json, salvo diversa indicazione. - La creazione accetta esattamente uno tra
url,textostorageId(dopoPOST /uploads), oppure un arrayvariants(vedi Varianti), oppure"kind": "folder"con unname(vedi Cartelle). Il mint restituisce{ "uploadUrl", "storageId" }. L’host carica i byte con una PUT suuploadUrl. Per i file piccoli puoi ancora usare il campo multipartfilesuPOST /links. - Durate:
7d,24h,30m,1woppure una data ISO. Campi:expires/expiresAt,starts/startsAt. - Limite di aperture: intero positivo opzionale
maxOpenings. Il link va in pausa dopo quel numero di aperture riuscite. Per renderlo di nuovo disponibile, alzamaxOpeningsoppure usaclearMaxOpenings. OmettimaxOpeningsper avere aperture illimitate. - Se uno slug esiste su due domini dello stesso proprietario, passa
?domain=/ il campo JSONdomain. - Errori:
{ "error": "..." }più uncodeopzionale. Gli sluglida.shgià occupati restituiscono409concode: "slug_taken". - Accesso: i nuovi link e le nuove cartelle sono
restricted, a meno che il body non impostiaccess(vedi Accesso e condivisione). Nelle risposte,urlè l’URL di condivisione (https://linkdash.dev/s/<token>), tranne quando il link è pubblico: in quel caso è l’URL breve. - Le scritture contano nella quota mensile di eventi (condivisione, revoca della condivisione e reset compresi). Elenco / lettura / statistiche / esportazione / elenco condivisioni / elementi condivisi con te / elenco e lettura dei webhook non contano. Le registrazioni di visite / download / riproduzioni contano comunque.
Endpoint
| 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 (senza 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 (senza 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 |
| (PUT dall’host dopo il 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 e auth logout sono flussi device nel browser. Non sono route Unkey.
GET /me
L’account con cui hai fatto l’accesso. { "userId": "...", "email": "...", "name": "..." }. Email e nome vengono omessi se non sono noti.
Creare un link URL
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"}'
Il body JSON accetta esattamente uno tra url, text o storageId, più i campi opzionali access (restricted predefinito | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (solo link URL) e folder (+ folderDomain) per creare il link dentro una cartella. La forma abbreviata crea una sola variante chiamata main; i campi password, starts, expires e maxOpenings al livello principale formano il gate del link. Risposta: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.
GET /links restituisce una pagina, { "items": [...], "cursor" }: ?limit= va da 1 a 100 (predefinito 50); passa ?cursor= preso dalla pagina precedente finché non vale null. q cerca parole intere (l’ultima come prefisso), ordinate per rilevanza. Gli elementi sono { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (le righe delle cartelle aggiungono items); il filtro kind aggiunge folder e group, il filtro status aggiunge mixed, e folder=<slug>|root (+ folderDomain) elenca una sola cartella o il livello principale. GET /links/:id restituisce il link completo con access e variants; il contenuto (destinationUrl / textContent / fileName) si trova su ogni variante.
Caricare un file
Fai il mint di un URL di upload ({uploadUrl,storageId}), carica i byte dall’host con una PUT, poi crea il link nello stesso flusso:
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}'
Per i file piccoli puoi ancora usare il multipart su POST /links:
curl https://api.linkdash.dev/v1/links \
-H "Authorization: Bearer ldash_..." \
-F "file=@./deck.pdf" \
-F "expires=7d" \
-F "slug=deck"
Campi multipart opzionali: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.
Aggiornamento, statistiche, CSV
PATCH /links/:id accetta JSON o multipart. Per sostituire i byte del file usa storageId dopo POST /uploads + PUT dall’host, oppure il campo multipart file (solo per link con una sola variante). --status / { "status": "expired" } viene rifiutato: usa expires. { "status": "scheduled" } viene rifiutato: usa starts. Il campo opzionale maxOpenings mette in pausa il link dopo quel numero di aperture; clearMaxOpenings rimuove il limite. sticky (booleano) e restartSplit (booleano) controllano l’assegnazione delle varianti; forwardParams (booleano) inoltra la query string del visitatore, vedi Inoltrare i parametri di query. access cambia chi può aprire il link; resetShareLink: true genera un nuovo URL di condivisione. Risposta: { "id", "url", "access", "status", "variantStatuses" }.
GET /links/:id/stats?last=24h restituisce visits, downloads, plays, visitsInLast, countries, referrers, variants (totali per variante), visitors e crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: bot e anteprime di link che hanno recuperato il link, mai conteggiati come visite; vedi Log dei crawler).
GET /links/export è un CSV con le colonne slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, una riga per variante (folder è lo slug della cartella che contiene il link; access è restricted, link o public). POST /links/import accetta CSV grezzo o il campo multipart file; le righe vengono raggruppate per slug + dominio (la prima riga crea il link con la sua variante, le righe successive aggiungono varianti; per i link esistenti vengono aggiornati i campi, poi le varianti vengono aggiornate o aggiunte in base al nome). Le righe con kind folder (e un name) creano cartelle, e la colonna folder sposta i link nelle cartelle solo dopo che tutte le righe sono state create. Se access è vuoto, i nuovi link sono restricted e quelli esistenti restano invariati.
DELETE /links/:id su una cartella accetta ?contents=keep (predefinito: gli elementi salgono di un livello) oppure ?contents=delete (vengono eliminati anche gli elementi e le cartelle contenuti).
Varianti
Ogni link è un contenitore di una o più varianti: un contenuto (url | file | text) con il proprio gate (password, paused, starts, expires, maxOpenings), un weight e condizioni opzionali sul visitatore when. Il link possiede slug, dominio, nome, tag, anteprima, il proprio gate (che prevale su quelli delle varianti), sticky (predefinito true) e splitVersion (incrementato da restartSplit). Senza variants, un link ha una sola variante chiamata main. Nomi: lettere minuscole, cifre e trattini interni, da 1 a 40 caratteri, univoci per link. Massimo 20 varianti per link.
Ogni visitatore riceve una sola variante: le varianti il cui when corrisponde formano il pool (se nessuna corrisponde, il pool è formato da quelle senza condizioni), poi ne viene scelta una in base al peso (con un hash sticky di visitatore + link + splitVersion, altrimenti a caso). I crawler ricevono la prima variante attiva senza condizioni. Il kind del link è group quando ci sono più varianti. Lo status del link è quello del gate del link se impostato, altrimenti lo stato comune a tutte le varianti, altrimenti mixed. variantStatuses conta { active, paused, expired, scheduled }.
Crea più varianti in una volta:
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"]}}]}'
Ogni variante: name (obbligatorio), uno tra url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. La creazione multipart supporta solo la forma abbreviata.
| Route | Body | Risposta |
|---|---|---|
GET /links/:id/variants |
— | array di varianti |
POST /links/:id/variants |
JSON o multipart file: name (obbligatorio), contenuto, password, starts, expires, maxOpenings, utm, weight, when |
la variante |
PATCH /links/:id/variants/:name |
name (rinomina), url, text, storageId / file, password, clearPassword, starts, clearStarts, expires, clearExpires, maxOpenings, clearMaxOpenings, status (active | paused), weight, when, clearWhen, utm |
la variante |
DELETE /links/:id/variants/:name |
— | { "id", "variant", "deleted": true } (l’ultima variante non può essere eliminata) |
Chiavi di when (array di stringhe; ogni chiave impostata deve corrispondere): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (prefisso), referrerHosts (suffisso dell’host).
Regole sui parametri di query
when.params è un array di massimo 10 regole sulla query string del visitatore (lida.sh/promo?src=newsletter); devono essere soddisfatte tutte. Ogni regola è { "key", "op", "value" }, con op uno tra equals | notEquals | includes | startsWith | endsWith | in (value è un elenco separato da | o da virgole) | exists | missing. value è obbligatorio tranne che per exists / missing. Le chiavi distinguono maiuscole e minuscole, i valori vengono confrontati in modo esatto.
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
I valori dei parametri vengono confrontati al momento dell’apertura e non vengono mai salvati nelle analytics.
Inoltrare i parametri di query
forwardParams (booleano sul link, predefinito false; impostabile su POST /links e PATCH /links/:id, restituito da GET /links/:id) aggiunge l’intera query string del visitatore alle varianti URL. I valori del visitatore sovrascrivono quelli salvati, utm compreso. Le varianti file e testo lo ignorano. Serve per il routing, non per il controllo degli accessi: chiunque può aggiungere parametri. I valori dei parametri non vengono salvati nelle analytics.
Cartelle
Una cartella è un link che elenca gli elementi che ci metti dentro. Vedi Cartelle per il modello.
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 | Risposta |
|---|---|---|
POST /links |
{ "kind": "folder", "name" } più i soliti campi del link; niente url, text, storageId o variants |
la cartella creata |
POST /links/:id/move |
{ "folder": "<slug>" } oppure { "folder": null } per il livello principale, folderDomain opzionale |
{ "id", "folder" } |
POST /links/:id/copy |
— | { "id", "url", "access", "kind", "variants", "folder", … } (stesso accesso, nuovo URL di condivisione, nessuna persona) |
Spostamento e copia contano ciascuno come un evento. Uno slug di cartella sconosciuto restituisce 404 (Folder "<slug>" not found); uno slug che non è una cartella, oppure lo spostamento di una cartella dentro sé stessa o in una sua sottocartella, restituisce 400. Le cartelle si annidano fino a un massimo di 32 livelli.
Accesso e condivisione
Ogni link e ogni cartella hanno un access: restricted (predefinito; il proprietario e le persone con cui è condiviso, con accesso effettuato, su https://linkdash.dev/s/<token>), link (chiunque abbia quell’URL) o public (chiunque, sull’URL breve). Impostalo su POST /links o PATCH /links/:id. Passa "access": "public" per i link destinati a essere pubblicati. Vedi Condivisione e accesso per capire come funzionano cartelle e visualizzatori.
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 | Risposta |
|---|---|---|
POST /links/:id/shares |
{ "emails": [...] } (da 1 a 50 email) |
{ "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" } (tutto quello che hai condiviso) |
GET /shared |
— | { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" } |
DELETE /shared/:id |
— | { "_id", "left": true } (:id è l’_id o il token di condivisione restituito da GET /shared) |
POST /links/:id/reset-link |
— | { "id", "access", "url" } |
POST /links/:id/shares accetta "role": "editor" per gli editor. Gli editor modificano gli elementi e vedono statistiche e attività, ma non possono mai toccare password, slug, dominio, accesso o condivisione, né eliminare, spostare o copiare (403); usano come :id l’_id dell’elemento o il token di condivisione, e una variante protetta da password resta locked: true finché non chiamano POST /links/:id/unlock (30 minuti; dopo dieci password errate in un’ora, 429). Se qualcun altro ha salvato prima di te, il salvataggio restituisce 409 solo quando la richiesta invia expectedVersion. Tutte le route di condivisione accettano ?domain= quando lo slug è ripetuto. accepted vale false finché quell’email non ha un account verificato; viaFolder indica che l’accesso deriva da una cartella superiore. Massimo 200 persone per elemento e 100 email di invito per account al giorno. GET /shares e GET /shared restituiscono una pagina alla volta: ?limit= va da 1 a 100 (predefinito 50); passa ?cursor= preso dalla pagina precedente finché cursor non vale null. Condivisione, revoca della condivisione e reset contano ciascuno come un evento; uscire da una condivisione no. Se l’accesso arriva da una cartella condivisa superiore, resta anche dopo che sei uscito.
Errori
| Stato | Quando |
|---|---|
| 400 | Validazione fallita, body mancante, tipi di creazione combinati |
| 401 | Chiave bearer mancante o non valida |
| 404 | Slug, dominio o cartella sconosciuti |
| 409 | Slug già occupato (code: "slug_taken") |
| 429 | Quota mensile di eventi raggiunta |
| 503 | Chiavi API non configurate su questo deployment |
Vedi webhook e domini personalizzati per i relativi endpoint.

