Saltar al contenido
LinkdashLinkdash
Español
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

API HTTP

API REST en https://api.linkdash.dev/v1 con una clave bearer del panel. Las mismas operaciones que la CLI y MCP.

URL base: https://api.linkdash.dev/v1

Autenticación: Authorization: Bearer ldash_... (crea claves en Panel → Claves de API). No inventes claves.

Referencia de la CLI: CLI. MCP: MCP. Precios / cuotas: Precios. Descubrimiento (sin autenticación): GET https://api.linkdash.dev/v1. Markdown plano: api.md.

Los ids públicos son slugs (deck, k3m9xq), no el _id de Convex. Los nombres de los campos JSON coinciden con la salida estándar de la CLI (id, url, kind, …).

Convenciones

  • JSON Content-Type: application/json, salvo que se indique lo contrario.
  • La creación acepta exactamente uno de url, text o storageId (este último después de POST /uploads), o un arreglo variants (consulta Variantes), o "kind": "folder" con un name (consulta Carpetas). La generación de la URL de subida devuelve { "uploadUrl", "storageId" }. El host hace PUT de los bytes a uploadUrl. Los archivos pequeños todavía pueden usar el campo multipart file en POST /links.
  • Duraciones: 7d, 24h, 30m, 1w o una fecha ISO. Campos: expires / expiresAt, starts / startsAt.
  • Límite de aperturas: entero positivo opcional maxOpenings. El enlace se pausa después de esa cantidad de aperturas exitosas. Aumenta maxOpenings, o usa clearMaxOpenings, para volver a servirlo. Omite maxOpenings para que sea ilimitado.
  • Si un slug existe en dos de los dominios del propietario, pasa ?domain= / el campo JSON domain.
  • Errores: { "error": "..." } más un code opcional. Los slugs de lida.sh ya ocupados devuelven 409 con code: "slug_taken".
  • Acceso: los enlaces y carpetas nuevos son restricted, salvo que el cuerpo defina access (consulta Acceso y uso compartido). url en las respuestas es la URL para compartir (https://linkdash.dev/s/<token>), salvo que el enlace sea público; en ese caso es la URL corta.
  • Las escrituras cuentan para la cuota mensual de eventos (incluidos compartir, dejar de compartir y restablecer). Listar / obtener / estadísticas / exportar / lista de personas con acceso / compartidos contigo / listar/obtener webhooks no cuentan. Las visitas, descargas y reproducciones registradas sí cuentan.

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 (sin 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 (sin 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 del host después de generar la 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 y auth logout son flujos de dispositivo en el navegador. No son rutas de Unkey.

GET /me

Cuenta con la sesión iniciada. { "userId": "...", "email": "...", "name": "..." }. El email y el nombre se omiten cuando no se conocen.

Crear un enlace de 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"}'

El cuerpo JSON acepta exactamente uno de url, text o storageId, más los campos opcionales access (restricted por defecto | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (solo enlaces de URL) y folder (+ folderDomain) para crearlo dentro de una carpeta. La forma abreviada crea una variante llamada main; los campos de nivel superior password, starts, expires y maxOpenings son la restricción del enlace. Respuesta: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.

GET /links devuelve una página, { "items": [...], "cursor" }: ?limit= va de 1 a 100 (50 por defecto); pasa ?cursor= de la página anterior hasta que sea null. q busca palabras completas (la última como prefijo), ordenadas por relevancia. Los elementos son { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (las filas de carpetas agregan items); el filtro kind agrega folder y group, el filtro status agrega mixed, y folder=<slug>|root (+ folderDomain) lista una carpeta o el nivel superior. GET /links/:id devuelve el enlace completo con access y variants; el contenido (destinationUrl / textContent / fileName) está en cada variante.

Subir un archivo

Genera una URL de subida ({uploadUrl,storageId}), haz PUT de los bytes desde el host y luego crea el enlace en el mismo flujo:

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

Los archivos pequeños todavía pueden usar multipart en POST /links:

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

Campos multipart opcionales: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.

Actualizar, estadísticas, CSV

PATCH /links/:id acepta JSON o multipart. Reemplaza los bytes del archivo con storageId después de POST /uploads + el PUT del host, o con el campo multipart file (solo enlaces con una sola variante). --status / { "status": "expired" } se rechaza; usa expires. { "status": "scheduled" } se rechaza; usa starts. El campo opcional maxOpenings pausa el enlace después de esa cantidad de aperturas; clearMaxOpenings elimina el límite. sticky (booleano) y restartSplit (booleano) controlan la asignación de variantes; forwardParams (booleano) reenvía la query string del visitante, consulta Reenviar parámetros de consulta. access cambia quién puede abrirlo; resetShareLink: true emite una nueva URL para compartir. Respuesta: { "id", "url", "access", "status", "variantStatuses" }.

GET /links/:id/stats?last=24h devuelve visits, downloads, plays, visitsInLast, countries, referrers, variants (totales por variante), visitors y crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: bots y vistas previas de enlaces que accedieron al enlace, que nunca se cuentan como visitas; consulta Registro de crawlers).

GET /links/export es un CSV con las columnas slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, una fila por variante (folder es el slug de la carpeta que lo contiene; access es restricted, link o public). POST /links/import acepta CSV sin procesar o el campo multipart file; las filas se agrupan por slug + dominio (la primera fila crea el enlace con su variante, las filas adicionales agregan variantes; en los enlaces existentes se actualizan los campos y luego se actualizan o agregan variantes por nombre). Las filas con kind folder (con un name) crean carpetas, y la columna folder ubica los enlaces una vez que existen todas las filas. Un access vacío hace que los enlaces nuevos sean restringidos y deja los enlaces existentes como están.

DELETE /links/:id en una carpeta acepta ?contents=keep (por defecto: los elementos suben un nivel) o ?contents=delete (también se eliminan los elementos y las carpetas que contiene).

Variantes

Cada enlace es un contenedor de una o más variantes: contenido (url | file | text) más su propia restricción (password, paused, starts, expires, maxOpenings), un weight y condiciones opcionales del visitante when. El enlace es dueño del slug, el dominio, el nombre, las etiquetas, la vista previa, su propia restricción (que tiene prioridad sobre las restricciones de las variantes), sticky (true por defecto) y splitVersion (que se incrementa con restartSplit). Sin variants, un enlace tiene una variante llamada main. Nombres: letras minúsculas, dígitos y guiones internos, de 1 a 40 caracteres, únicos por enlace. Máximo 20 variantes por enlace.

Cada visitante recibe una variante: las variantes cuyo when coincide forman el grupo (si ninguna coincide, lo forman las variantes incondicionales), y luego se hace una selección ponderada (hash persistente del visitante + enlace + splitVersion, o aleatoria en caso contrario). Los crawlers reciben la primera variante incondicional activa. El kind del enlace es group cuando tiene varias variantes. El status del enlace es la restricción del enlace cuando está definida; si no, el estado que comparten todas las variantes; si no, mixed. variantStatuses cuenta { active, paused, expired, scheduled }.

Crea varias variantes a la vez:

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

Cada variante: name (obligatorio), uno de url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. La creación multipart solo admite la forma abreviada.

Ruta Cuerpo Respuesta
GET /links/:id/variants — arreglo de variantes
POST /links/:id/variants JSON o multipart file: name (obligatorio), contenido, password, starts, expires, maxOpenings, utm, weight, when la variante
PATCH /links/:id/variants/:name name (renombrar), 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 } (la última variante no se puede eliminar)

Claves de when (arreglos de strings; cada clave definida debe coincidir): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (prefijo), referrerHosts (sufijo del host).

Reglas de parámetros de consulta

when.params es un arreglo de hasta 10 reglas sobre la query string del visitante (lida.sh/promo?src=newsletter); todas las reglas deben cumplirse. Cada regla es { "key", "op", "value" } con op igual a uno de equals | notEquals | includes | startsWith | endsWith | in (value es una lista separada por | o por comas) | exists | missing. value es obligatorio, excepto para exists / missing. Las claves distinguen mayúsculas de minúsculas y los valores se comparan de forma exacta.

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

Los valores de los parámetros se evalúan al momento de la apertura y nunca se guardan en las analíticas.

Reenviar parámetros de consulta

forwardParams (booleano en el enlace, false por defecto; se puede definir en POST /links y PATCH /links/:id, y lo devuelve GET /links/:id) agrega la query string completa del visitante a las variantes de URL. Los valores del visitante sobrescriben los guardados, incluido utm. Las variantes de archivo y de texto lo ignoran. Esto es enrutamiento, no control de acceso: cualquiera puede agregar parámetros. Los valores de los parámetros no se guardan en las analíticas.

Carpetas

Una carpeta es un enlace que lista los elementos que pones en ella. Consulta Carpetas para conocer el modelo.

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_..."
Ruta Cuerpo Respuesta
POST /links { "kind": "folder", "name" } más los campos habituales de un enlace; sin url, text, storageId ni variants la carpeta creada
POST /links/:id/move { "folder": "<slug>" } o { "folder": null } para el nivel superior, folderDomain opcional { "id", "folder" }
POST /links/:id/copy — { "id", "url", "access", "kind", "variants", "folder", … } (mismo acceso, nueva URL para compartir, sin personas)

Mover y copiar cuentan como un evento cada uno. Un slug de carpeta desconocido devuelve 404 (Folder "<slug>" not found); un slug que no es una carpeta, o mover una carpeta dentro de sí misma o de una carpeta que está debajo de ella, devuelve 400. Las carpetas se anidan hasta 32 niveles como máximo.

Acceso y uso compartido

Cada enlace y carpeta tiene access: restricted (por defecto; el propietario y las personas con quienes se comparte, con sesión iniciada, en https://linkdash.dev/s/<token>), link (cualquiera que tenga esa URL) o public (cualquiera, en la URL corta). Defínelo en POST /links o PATCH /links/:id. Pasa "access": "public" para enlaces que se van a publicar abiertamente. Consulta Uso compartido y acceso para ver cómo funcionan las carpetas y los lectores.

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_..."
Ruta Cuerpo Respuesta
POST /links/:id/shares { "emails": [...] } (de 1 a 50 emails) { "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" } (todo lo que compartiste)
GET /shared — { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }
DELETE /shared/:id — { "_id", "left": true } (:id es el _id o el token para compartir de GET /shared)
POST /links/:id/reset-link — { "id", "access", "url" }

POST /links/:id/shares acepta "role": "editor" para editores. Los editores modifican elementos y ven estadísticas y actividad, pero nunca contraseñas, slug, dominio, acceso, uso compartido, eliminar, mover ni copiar (403); usan el _id del elemento o el token para compartir como :id, y una variante protegida con contraseña permanece en locked: true hasta POST /links/:id/unlock (30 minutos; diez contraseñas incorrectas en una hora y luego 429). Guardar después de que otra persona guardó devuelve 409 solo cuando la solicitud envía expectedVersion. Todas las rutas de uso compartido aceptan ?domain= cuando el slug se repite. accepted es false hasta que ese email tenga una cuenta verificada; viaFolder significa que el acceso proviene de una carpeta superior. Hasta 200 personas por elemento y 100 emails de invitación por cuenta por día. GET /shares y GET /shared devuelven una página a la vez: ?limit= va de 1 a 100 (50 por defecto); pasa ?cursor= de la página anterior hasta que cursor sea null. Compartir, dejar de compartir y restablecer cuentan como un evento cada uno; salir no cuenta. El acceso a través de una carpeta compartida superior se mantiene después de salir.

Errores

Estado Cuándo
400 Validación, cuerpo faltante, tipos de creación mezclados
401 Clave bearer faltante o inválida
404 Slug, dominio o carpeta desconocidos
409 Slug ocupado (code: "slug_taken")
429 Se alcanzó la cuota mensual de eventos
503 Las claves de API no están configuradas en este despliegue

Consulta webhooks y dominios personalizados para esos endpoints.

¿Te ha resultado útil esta página?