Vai al contenuto
LinkdashLinkdash
Italiano
Esc
↑↓naviga↵apri⌘Janteprima
In questa pagina

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, text o storageId (dopo POST /uploads), oppure un array variants (vedi Varianti), oppure "kind": "folder" con un name (vedi Cartelle). Il mint restituisce { "uploadUrl", "storageId" }. L’host carica i byte con una PUT su uploadUrl. Per i file piccoli puoi ancora usare il campo multipart file su POST /links.
  • Durate: 7d, 24h, 30m, 1w oppure 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, alza maxOpenings oppure usa clearMaxOpenings. Ometti maxOpenings per avere aperture illimitate.
  • Se uno slug esiste su due domini dello stesso proprietario, passa ?domain= / il campo JSON domain.
  • Errori: { "error": "..." } più un code opzionale. Gli slug lida.sh già occupati restituiscono 409 con code: "slug_taken".
  • Accesso: i nuovi link e le nuove cartelle sono restricted, a meno che il body non imposti access (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.

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.

Questa pagina ti è stata utile?