Aller au contenu
LinkdashLinkdash
Français
Esc
↑↓naviguer↵ouvrir⌘Japerçu
Sur cette page

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, text ou storageId (obtenu après POST /uploads), ou un tableau variants (voir Variantes), ou "kind": "folder" avec un name (voir Dossiers). 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). 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" }
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’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.

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.

Cette page vous a-t-elle été utile ?