---
title: API HTTP
description: >-
  API REST en https://api.linkdash.dev/v1 con una clave bearer del panel. Las
  mismas operaciones que la CLI y MCP.
sidebar:
  label: API HTTP
  order: 4
---
URL base: `https://api.linkdash.dev/v1`

Autenticación: `Authorization: Bearer ldash_...` (crea claves en [Panel → Claves de API](https://linkdash.dev/dashboard/keys)). No inventes claves.

Referencia de la CLI: [CLI](/es/cli). MCP: [MCP](/es/mcp). Precios / cuotas: [Precios](/es/pricing). Descubrimiento (sin autenticación): `GET https://api.linkdash.dev/v1`. Markdown plano: [api.md](https://linkdash.dev/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](#variants)), **o** `"kind": "folder"` con un `name` (consulta [Carpetas](#folders)). 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](#access-and-sharing)). `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" }` | `{ "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` (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

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

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:

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

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

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

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

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

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.

```json
{ "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](/es/folders) para conocer el modelo.

```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_..."
```

| 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](/es/sharing) para ver cómo funcionan las carpetas y los lectores.

```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_..."
```

| 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](/es/webhooks) y [dominios personalizados](/es/domains) para esos endpoints.
