API HTTP
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.
URL de base : https://api.linkdash.dev/v1
Authentification : Authorization: Bearer ldash_... (créez vos clés dans Tableau de bord → Clés API). N’inventez pas de clés.
Référence de la CLI : CLI. MCP : MCP. Tarifs et quotas : Tarifs. Découverte (sans authentification) : GET https://api.linkdash.dev/v1. Version Markdown brut : 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,textoustorageId(obtenu aprèsPOST /uploads), ou un tableauvariants(voir Variantes), ou"kind": "folder"avec unname(voir Dossiers). La génération d’une URL d’upload renvoie{ "uploadUrl", "storageId" }. L’hôte envoie ensuite les octets par PUT versuploadUrl. Pour les petits fichiers, vous pouvez aussi envoyer un champ multipartfilesurPOST /links. - Durées :
7d,24h,30m,1wou 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, augmentezmaxOpeningsou utilisezclearMaxOpenings. SansmaxOpenings, le nombre d’ouvertures est illimité. - Si un slug existe sur deux domaines du propriétaire, passez
?domain=ou le champ JSONdomain. - Erreurs :
{ "error": "..." }, avec uncodefacultatif. Un sluglida.shdéjà pris renvoie409aveccode: "slug_taken". - Accès : les nouveaux liens et dossiers sont
restricted, sauf si le corps définitaccess(voir Accès et partage). Dans les réponses,urlest 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" } |
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
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 :
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 :
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). 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).
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 :
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.
{ "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.
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’adressehttps://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.
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 et domaines personnalisés.

