API pública
La API de linkable.id permite que tus propios sistemas, como un CRM, una herramienta de campañas o un script, creen enlaces cortos, descarguen sus códigos QR y lean sus estadísticas de clics. Es una API REST en JSON sobre HTTPS.
Disponibilidad: los planes Business, Agency y Enterprise. Pídenos activarla para tu cuenta.
El documento OpenAPI, para importarlo en Postman, Insomnia o un generador de clientes, está en el propio linkable.id: inicia sesión, abre Configuración → Tokens de API y haz clic en Descargar documento OpenAPI en Referencia de la API. La misma sección muestra la URL base de tu API con un botón para copiarla.
Inicio rápido
- En Configuración → Tokens de API, crea un token con los permisos que necesitas. Consulta Tokens de API.
- Copia la URL base desde Referencia de la API en la misma página. Es
https://{dominio-de-administración}/api/v1, donde el dominio de administración es la dirección donde inicias sesión en linkable.id. - Guarda el token en una variable de entorno (así no queda escrito en tus scripts) y envíalo como token Bearer:
export LINKABLE_API_TOKEN="pega-aquí-tu-token"
curl https://tu-dominio-de-administracion/api/v1/me \
-H "Authorization: Bearer $LINKABLE_API_TOKEN"/me responde con el espacio de trabajo, los permisos y el vencimiento del token, una buena primera comprobación.
Un token funciona en un espacio de trabajo. Todo lo que crea o lee pertenece a ese espacio de trabajo.
Permisos
| Permiso | Permite al token |
|---|---|
links:read | Listar y leer enlaces, y descargar sus códigos QR |
links:write | Crear y actualizar enlaces |
stats:read | Leer las estadísticas de clics de los enlaces |
Un token nunca puede hacer más de lo que permite el rol de su propietario. Si un administrador quita un permiso de tu rol, tus tokens lo pierden de inmediato.
Enlaces
Listar enlaces. Del más reciente al más antiguo, 25 por página (hasta 100 con limit). Filtra con search (nombre), tag y domain (nombre de dominio).
curl "https://tu-dominio-de-administracion/api/v1/links?tag=primavera&limit=50" \
-H "Authorization: Bearer $LINKABLE_API_TOKEN"Crear un enlace. name, target y domain (uno de tus dominios, por su nombre) son obligatorios. Opcionales: description, tags (nombres; los nuevos se crean) y los parámetros UTM utm_id, utm_source, utm_medium, utm_campaign, utm_term, utm_content. La dirección corta se genera, y el enlace usa el tema QR predeterminado de tu espacio de trabajo.
curl https://tu-dominio-de-administracion/api/v1/links \
-H "Authorization: Bearer $LINKABLE_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-1234" \
-d '{"name": "Volante de primavera", "target": "https://tienda.example.com/primavera", "domain": "go.example.com", "tags": ["primavera"], "utm_source": "volante"}'Leer o actualizar un enlace. GET /links/{id} y PATCH /links/{id}. Un PATCH cambia solo los campos que envías. Un valor UTM vacío quita ese parámetro, y tags reemplaza toda la lista. La dirección corta nunca cambia. El enlace corto de una página de marca, un sitio o una Página personalizada siempre lleva a su página, así que su target no se puede cambiar.
Código QR. GET /links/{id}/qr.svg devuelve el código QR del enlace en SVG, con su tema QR.
Estadísticas
Clics de un enlace en el tiempo:
curl "https://tu-dominio-de-administracion/api/v1/links/42/stats?from=2026-09-01&to=2026-09-30&interval=week" \
-H "Authorization: Bearer $LINKABLE_API_TOKEN"Clics por enlace en un periodo: GET /stats/links, en páginas como la lista de enlaces.
Ambos aceptan from y to (fechas AAAA-MM-DD, por defecto los últimos 30 días) e interval (auto, day, week, month, quarter o year). El periodo termina hoy como máximo y no empieza antes de lo que permite el historial de analítica de tu plan. Un periodo largo pedido por day se agrupa con un intervalo más amplio. Cada respuesta indica el from, el to y el interval que usó realmente.
Páginas
Las listas devuelven data y next_cursor. Envía next_cursor como cursor para obtener la página siguiente; es null en la última página.
Reintentar con seguridad
Agrega un encabezado Idempotency-Key (cualquier texto único de hasta 255 caracteres) a un POST. Si una solicitud exitosa se reintenta con la misma clave y el mismo cuerpo dentro de 24 horas, recibes de nuevo la primera respuesta, marcada con Idempotent-Replayed: true, en lugar de un segundo enlace. La misma clave con otro cuerpo se rechaza con 409, igual que un reintento mientras la primera solicitud sigue en curso. Una solicitud rechazada (por ejemplo, un 422) no se guarda, así que puedes corregir el cuerpo y reintentar con la misma clave.
Errores
Los errores siguen RFC 9457 (application/problem+json):
{
"type": "urn:linkable:problem:validation_failed",
"title": "Validación fallida",
"status": 422,
"detail": "Algunos campos no son válidos. Revisa errors.",
"errors": { "domain": ["El campo domain seleccionado no es válido."] }
}| Estado | Cuándo |
|---|---|
| 401 | El token falta, venció o fue revocado, o su propietario salió del espacio de trabajo |
| 403 | El token no tiene el permiso, o tu plan no incluye la API |
| 404 | No existe nada con ese id en el espacio de trabajo del token |
| 409 | Una Idempotency-Key usada con otro cuerpo, o su primera solicitud aún está en curso |
| 422 | Campos no válidos (ver errors) |
| 429 | Demasiadas solicitudes (ver abajo) |
type es estable, así que basa el manejo de errores en él y no en el texto. detail está en el idioma del propietario del token.
Límites
- Frecuencia: 120 solicitudes por minuto por token, indicadas en los encabezados
X-RateLimit-LimityX-RateLimit-Remaining. Por encima, recibes 429 conRetry-After(segundos). Las solicitudes con un token faltante o no válido se limitan aparte, por IP. - Llamadas mensuales: tu plan incluye una cantidad de llamadas a la API por mes, que ves en Plan y uso. Superarla envía un aviso a tus administradores y nunca detiene la API.
Versiones
Esta es la versión 1 (/api/v1). Dentro de v1 solo agregamos: endpoints nuevos, campos opcionales nuevos, campos nuevos en las respuestas. Haz que tu integración ignore los campos que no conoce. Un cambio incompatible llegaría como /api/v2, anunciado en Novedades al menos seis meses antes de que v1 deje de funcionar.
Con Claude
Claude no usa la API pública: trabaja con el conector de Claude, que cubre mucho más que los enlaces y actúa como la persona que lo conectó. Usa la API para tus propias integraciones, con un token; usa el conector para trabajar con Claude.