---
title: API HTTP
description: >-
  REST su https://api.linkdash.dev/v1 con una chiave bearer creata dalla
  dashboard. Offre le stesse operazioni della CLI e dell'MCP.
sidebar:
  label: API HTTP
  order: 4
---
URL di base: `https://api.linkdash.dev/v1`

Autenticazione: `Authorization: Bearer ldash_...` (crea le chiavi in [Dashboard → Chiavi API](https://linkdash.dev/dashboard/keys)). Non inventare chiavi.

Riferimento CLI: [CLI](/it/cli). MCP: [MCP](/it/mcp). Prezzi / quote: [Prezzi](/it/pricing). Discovery (senza autenticazione): `GET https://api.linkdash.dev/v1`. Markdown semplice: [api.md](https://linkdash.dev/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](#variants)), **oppure** `"kind": "folder"` con un `name` (vedi [Cartelle](#folders)). 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](#access-and-sharing)). 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" }` | `{ "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` (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

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

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:

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

Per i file piccoli puoi ancora usare il multipart su `POST /links`:

```bash
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](#forward-query-parameters). `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](https://linkdash.dev/pricing.md)).

`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:

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

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.

```json
{ "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](/it/folders) per il modello.

```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 | 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](/it/sharing) per capire come funzionano cartelle e visualizzatori.

```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 | 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](/it/webhooks) e [domini personalizzati](/it/domains) per i relativi endpoint.
