---
title: API HTTP
description: >-
  API REST sur https://api.linkdash.dev/v1 avec une clé bearer créée dans le
  tableau de bord. Elle propose les mêmes opérations que la CLI et le MCP.
sidebar:
  label: API HTTP
  order: 4
---
URL de base : `https://api.linkdash.dev/v1`

Authentification : `Authorization: Bearer ldash_...` (créez vos clés dans [Tableau de bord → Clés API](https://linkdash.dev/dashboard/keys)). N'inventez pas de clés.

Référence de la CLI : [CLI](/fr/cli). MCP : [MCP](/fr/mcp). Tarifs et quotas : [Tarifs](/fr/pricing). Découverte (sans authentification) : `GET https://api.linkdash.dev/v1`. Version Markdown brut : [api.md](https://linkdash.dev/api.md).

Les identifiants publics sont des slugs (`deck`, `k3m9xq`) et non des `_id` Convex. Les noms des champs JSON sont les mêmes que dans la sortie stdout de la CLI (`id`, `url`, `kind`, …).

## Conventions

- Sauf mention contraire, le corps est en JSON avec `Content-Type: application/json`.
- La création accepte un seul champ parmi `url`, `text` ou `storageId` (obtenu après `POST /uploads`), **ou** un tableau `variants` (voir [Variantes](#variants)), **ou** `"kind": "folder"` avec un `name` (voir [Dossiers](#folders)). La génération d'une URL d'upload renvoie `{ "uploadUrl", "storageId" }`. L'hôte envoie ensuite les octets par PUT vers `uploadUrl`. Pour les petits fichiers, vous pouvez aussi envoyer un champ multipart `file` sur `POST /links`.
- Durées : `7d`, `24h`, `30m`, `1w` ou une date ISO. Champs : `expires` / `expiresAt`, `starts` / `startsAt`.
- Limite d'ouvertures : entier positif facultatif `maxOpenings`. Le lien est mis en pause après ce nombre d'ouvertures réussies. Pour qu'il soit de nouveau servi, augmentez `maxOpenings` ou utilisez `clearMaxOpenings`. Sans `maxOpenings`, le nombre d'ouvertures est illimité.
- Si un slug existe sur deux domaines du propriétaire, passez `?domain=` ou le champ JSON `domain`.
- Erreurs : `{ "error": "..." }`, avec un `code` facultatif. Un slug `lida.sh` déjà pris renvoie `409` avec `code: "slug_taken"`.
- Accès : les nouveaux liens et dossiers sont `restricted`, sauf si le corps définit `access` (voir [Accès et partage](#access-and-sharing)). Dans les réponses, `url` est l'URL de partage (`https://linkdash.dev/s/<token>`), sauf pour un lien public, où c'est l'URL courte.
- Les écritures sont décomptées du quota mensuel d'événements, y compris le partage, la révocation du partage et la réinitialisation. Les opérations suivantes ne le sont pas : liste, lecture, statistiques, export, liste des partages, éléments partagés avec vous, liste et lecture des webhooks. Les visites, téléchargements et lectures enregistrés sont toujours décomptés.

## Endpoints

| 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` (sans 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` (sans `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 par l'hôte après génération de l'URL) | `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` et `auth logout` sont des flux d'autorisation d'appareil qui passent par le navigateur. Ce ne sont pas des routes Unkey.

## `GET /me`

Renvoie le compte connecté : `{ "userId": "...", "email": "...", "name": "..." }`. L'e-mail et le nom sont omis s'ils sont inconnus.

## Créer un lien 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"}'
```

Le corps JSON accepte un seul champ parmi `url`, `text` ou `storageId`. Il accepte aussi les champs facultatifs `access` (`restricted` par défaut \| `link` \| `public`), `slug`, `name`, `tags`, `starts`, `expires`, `maxOpenings`, `password`, `domain`, `previewName`, `previewDescription`, `previewImageStorageId`, `sticky`, `forwardParams`, `utm` (liens URL uniquement), ainsi que `folder` (+ `folderDomain`) pour créer le lien dans un dossier. Cette forme abrégée crée une seule variante nommée `main`. Les champs `password`, `starts`, `expires` et `maxOpenings` de premier niveau définissent la barrière d'accès du lien. Réponse : `{ "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }`.

`GET /links` renvoie une page à la fois, sous la forme `{ "items": [...], "cursor" }`. `?limit=` va de 1 à 100 (50 par défaut). Passez le `?cursor=` de la page précédente jusqu'à ce qu'il vaille `null`. `q` recherche des mots entiers (le dernier est traité comme un préfixe) et trie les résultats par pertinence. Les éléments ont la forme `{ id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id }` (les lignes de dossier ajoutent `items`). Le filtre `kind` accepte aussi `folder` et `group`, et le filtre `status` accepte aussi `mixed`. `folder=<slug>|root` (+ `folderDomain`) liste le contenu d'un dossier ou le niveau racine. `GET /links/:id` renvoie le lien complet avec `access` et `variants`. Le contenu (`destinationUrl` / `textContent` / `fileName`) est porté par chaque variante.

## Uploader un fichier

Générez une URL d'upload (`{uploadUrl,storageId}`), envoyez les octets par PUT depuis l'hôte, puis créez le lien dans le même flux :

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

Pour les petits fichiers, vous pouvez aussi envoyer du multipart sur `POST /links` :

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -F "file=@./deck.pdf" \
  -F "expires=7d" \
  -F "slug=deck"
```

Champs multipart facultatifs : `access`, `slug`, `name`, `tags`, `starts` / `startsAt`, `password`, `expires`, `maxOpenings`, `domain`, `previewName`, `previewDescription`, `previewImage`.

## Mise à jour, statistiques, CSV

`PATCH /links/:id` accepte du JSON ou du multipart. Pour remplacer les octets d'un fichier, passez un `storageId` obtenu via `POST /uploads` suivi du PUT par l'hôte, ou envoyez un champ multipart `file` (liens à une seule variante uniquement). `--status` / `{ "status": "expired" }` est refusé : utilisez `expires`. `{ "status": "scheduled" }` est refusé : utilisez `starts`. Le champ facultatif `maxOpenings` met le lien en pause après ce nombre d'ouvertures, et `clearMaxOpenings` supprime la limite. `sticky` (booléen) et `restartSplit` (booléen) contrôlent l'attribution des variantes. `forwardParams` (booléen) transmet la query string du visiteur (voir [Transférer les paramètres de requête](#forward-query-parameters)). `access` modifie qui peut ouvrir le lien, et `resetShareLink: true` génère une nouvelle URL de partage. Réponse : `{ "id", "url", "access", "status", "variantStatuses" }`.

`GET /links/:id/stats?last=24h` renvoie `visits`, `downloads`, `plays`, `visitsInLast`, `countries`, `referrers`, `variants` (totaux par variante), `visitors` et `crawlers`. `crawlers` a la forme `[{ "crawler", "company", "category", "hits", "lastSeen" }]` et liste les bots et les générateurs d'aperçus de liens qui ont récupéré le lien. Ces accès ne sont jamais comptés comme des visites (voir [Journal des crawlers](https://linkdash.dev/pricing.md)).

`GET /links/export` renvoie un CSV avec les colonnes `slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`, à raison d'une ligne par variante. `folder` contient le slug du dossier parent, et `access` vaut `restricted`, `link` ou `public`. `POST /links/import` accepte du CSV brut ou un champ multipart `file`. Les lignes sont regroupées par slug + domaine :

- la première ligne crée le lien avec sa variante, et les lignes suivantes ajoutent des variantes ;
- pour un lien existant, les champs du lien sont mis à jour, puis les variantes sont mises à jour ou ajoutées selon leur nom.

Les lignes de `kind` `folder` (avec un `name`) créent des dossiers. La colonne `folder` place les liens dans leur dossier une fois toutes les lignes créées. Si `access` est vide, les nouveaux liens sont restreints et les liens existants restent inchangés.

Sur un dossier, `DELETE /links/:id` accepte `?contents=keep` (par défaut : les éléments remontent d'un niveau) ou `?contents=delete` (les éléments et sous-dossiers sont supprimés eux aussi).

## Variantes

Chaque lien est un conteneur d'une ou plusieurs **variantes**. Une variante comprend :

- un contenu (`url` | `file` | `text`) ;
- sa propre barrière d'accès (`password`, `paused`, `starts`, `expires`, `maxOpenings`) ;
- un poids `weight` ;
- des conditions facultatives sur le visiteur (`when`).

Le lien porte le slug, le domaine, le nom, les tags, l'aperçu, sa propre barrière d'accès (prioritaire sur celles des variantes), `sticky` (`true` par défaut) et `splitVersion` (incrémenté par `restartSplit`). Sans `variants`, un lien a une seule variante nommée `main`. Les noms de variante contiennent des lettres minuscules, des chiffres et des tirets (pas en début ni en fin), font de 1 à 40 caractères et sont uniques au sein d'un lien. Un lien compte au maximum 20 variantes.

Chaque visiteur reçoit une seule variante. Les variantes dont le `when` correspond au visiteur forment le pool de tirage. Si aucune ne correspond, ce sont les variantes sans condition qui le forment. Une variante est ensuite tirée en fonction des poids : par un hash stable du visiteur, du lien et de `splitVersion` si `sticky` est actif, au hasard sinon. Les crawlers reçoivent la première variante active sans condition. Un lien à plusieurs variantes a le `kind` `group`. Le `status` du lien est celui de sa barrière d'accès si elle est définie. Sinon, c'est le statut commun à toutes les variantes, ou `mixed` si elles diffèrent. `variantStatuses` compte les variantes par statut : `{ active, paused, expired, scheduled }`.

Créer plusieurs variantes en une seule requête :

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

Chaque variante accepte `name` (obligatoire), un seul champ parmi `url` | `text` | `storageId` (+ `fileName`, `fileType`, `fileSize`), ainsi que `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight` et `when`. La création en multipart ne prend en charge que la forme abrégée.

| Route | Corps | Réponse |
| --- | --- | --- |
| `GET /links/:id/variants` | — | tableau des variantes |
| `POST /links/:id/variants` | JSON ou multipart `file` : `name` (obligatoire), contenu, `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when` | la variante |
| `PATCH /links/:id/variants/:name` | `name` (renommage), `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 }` (impossible de supprimer la dernière variante) |

Clés de `when` (tableaux de chaînes ; chaque clé définie doit correspondre) : `countries` (ISO-2), `devices` (`mobile` | `tablet` | `desktop`), `os` (`windows` | `macos` | `android` | `ios` | `linux` | `other`), `browsers` (`edge` | `chrome` | `firefox` | `safari` | `other`), `languages` (préfixe), `referrerHosts` (suffixe d'hôte).

### Règles sur les paramètres de requête

`when.params` est un tableau de 10 règles au maximum, évaluées sur la query string du visiteur (`lida.sh/promo?src=newsletter`). Toutes les règles doivent être satisfaites. Chaque règle a la forme `{ "key", "op", "value" }`. `op` vaut l'une des valeurs suivantes : `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` est alors une liste séparée par des `|` ou des virgules) | `exists` | `missing`. `value` est obligatoire, sauf pour `exists` / `missing`. Les clés sont sensibles à la casse, et les valeurs sont comparées à l'identique.

```json
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
```

Les valeurs des paramètres sont évaluées à l'ouverture et ne sont jamais stockées dans les statistiques.

### Transférer les paramètres de requête

`forwardParams` est un booléen défini sur le lien (`false` par défaut). Il se définit sur `POST /links` et `PATCH /links/:id`, et `GET /links/:id` le renvoie. Lorsqu'il est actif, la query string complète du visiteur est ajoutée aux variantes URL. Les valeurs du visiteur remplacent les valeurs enregistrées, `utm` compris. Les variantes fichier et texte l'ignorent. Il s'agit de routage et non de contrôle d'accès : n'importe qui peut ajouter des paramètres. Les valeurs des paramètres ne sont pas stockées dans les statistiques.

## Dossiers

Un dossier est un lien qui liste les éléments que vous y placez. Le modèle est décrit dans [Dossiers](/fr/folders).

```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 | Corps | Réponse |
| --- | --- | --- |
| `POST /links` | `{ "kind": "folder", "name" }` plus les champs habituels d'un lien ; pas de `url`, `text`, `storageId` ni `variants` | le dossier créé |
| `POST /links/:id/move` | `{ "folder": "<slug>" }` ou `{ "folder": null }` pour la racine, `folderDomain` facultatif | `{ "id", "folder" }` |
| `POST /links/:id/copy` | — | `{ "id", "url", "access", "kind", "variants", "folder", … }` (même accès, nouvelle URL de partage, aucune personne invitée) |

Un déplacement ou une copie compte chacun comme un événement. Un slug de dossier inconnu renvoie `404` (`Folder "<slug>" not found`). Les cas suivants renvoient `400` : un slug qui ne désigne pas un dossier, ou le déplacement d'un dossier dans lui-même ou dans l'un de ses sous-dossiers. Les dossiers s'imbriquent sur 32 niveaux au maximum.

## Accès et partage

Chaque lien et chaque dossier a un niveau d'accès `access` :

- `restricted` (par défaut) : le propriétaire et les personnes avec qui l'élément est partagé, une fois connectés, à l'adresse `https://linkdash.dev/s/<token>` ;
- `link` : toute personne disposant de cette URL ;
- `public` : tout le monde, à l'URL courte.

Définissez-le sur `POST /links` ou `PATCH /links/:id`. Passez `"access": "public"` pour les liens destinés à être publiés. Le fonctionnement des dossiers et des lecteurs est décrit dans [Partage et accès](/fr/sharing).

```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 | Corps | Réponse |
| --- | --- | --- |
| `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" }` (tout ce que vous avez partagé) |
| `GET /shared` | — | `{ "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }` |
| `DELETE /shared/:id` | — | `{ "_id", "left": true }` (`:id` est le `_id` ou le jeton de partage renvoyé par `GET /shared`) |
| `POST /links/:id/reset-link` | — | `{ "id", "access", "url" }` |

Pour inviter des éditeurs, passez `"role": "editor"` à `POST /links/:id/shares`.

Les éditeurs peuvent modifier les éléments et consulter les statistiques et l'activité. Ils n'ont en revanche jamais accès aux mots de passe, au slug, au domaine, au niveau d'accès ni au partage, et ne peuvent pas supprimer, déplacer ou copier (`403`). Ils utilisent le `_id` de l'élément ou son jeton de partage comme `:id`. Une variante protégée par mot de passe reste `locked: true` jusqu'à un appel à `POST /links/:id/unlock`. Le déverrouillage dure 30 minutes. Au-delà de dix mots de passe erronés en une heure, l'API renvoie `429`. Un enregistrement fait après celui d'une autre personne renvoie `409`, uniquement si la requête envoie `expectedVersion`.

Toutes les routes de partage acceptent `?domain=` lorsque le slug existe sur plusieurs domaines. `accepted` vaut `false` tant que l'adresse e-mail n'est pas associée à un compte vérifié. `viaFolder` indique que l'accès provient d'un dossier parent. Un élément peut être partagé avec 200 personnes au maximum, et un compte peut envoyer 100 e-mails d'invitation par jour au maximum.

`GET /shares` et `GET /shared` renvoient une page à la fois. `?limit=` va de 1 à 100 (50 par défaut). Passez le `?cursor=` de la page précédente jusqu'à ce que `cursor` vaille `null`.

Le partage, la révocation du partage et la réinitialisation comptent chacun comme un événement. Quitter un partage n'en compte pas. Si vous quittez un partage, l'accès obtenu via un dossier parent partagé est conservé.

## Erreurs

| Statut | Cas |
| --- | --- |
| 400 | Erreur de validation, corps manquant, types de création mélangés |
| 401 | Clé bearer manquante ou invalide |
| 404 | Slug, domaine ou dossier inconnu |
| 409 | Slug déjà pris (`code: "slug_taken"`) |
| 429 | Quota mensuel d'événements atteint |
| 503 | Clés API non configurées sur ce déploiement |

Les endpoints correspondants sont décrits dans [webhooks](/fr/webhooks) et [domaines personnalisés](/fr/domains).
