Documentación de la API de urlf.ly

Resumen

• URL base: https://urlf.ly/api/v1
• Las respuestas son JSON. Envía el cuerpo de la petición como JSON con Content-Type: application/json, o codificado como formulario.
• Cada petición necesita una clave de API. Una clave actúa sobre los enlaces del miembro que la creó.
• Las horas están en UTC, con el formato YYYY-MM-DD HH:MM:SS.
• Una petición a https://urlf.ly/api/v1 sin más no necesita clave y devuelve el nombre y la versión de la API.

Autenticación

1. Inicia sesión y abre Claves de API desde tu panel.
2. Ponle un nombre a la clave y pulsa Crear clave. La clave completa, que empieza por uf_, solo se muestra una vez. Guárdala en un lugar seguro.
3. Envíala en cada petición, como token Bearer o en una cabecera X-Api-Key.

curl -H "Authorization: Bearer uf_YOUR_API_KEY" https://urlf.ly/api/v1/links

curl -H "X-Api-Key: uf_YOUR_API_KEY" https://urlf.ly/api/v1/links

Puedes tener hasta 20 claves activas y revocar cualquiera de ellas desde la misma página. Solo se guarda un hash de cada clave. Una clave ausente, incorrecta o revocada recibe 401. Tras 30 intentos fallidos desde una misma dirección IP en 10 minutos, los siguientes intentos reciben 429 hasta que pasa ese periodo.

Límites de peticiones

Cada clave puede hacer 1.000 peticiones por hora. Cuando se acepta una clave y la API está incluida en el plan de su propietario, las respuestas llevan X-RateLimit-Limit: 1000. Al superar el límite recibes 429 con una cabecera Retry-After que indica los segundos que hay que esperar.

El cuerpo de las peticiones está limitado a 64 KB.

Endpoints

Las rutas son relativas a la URL base. {ref} es el id numérico del enlace o su code corto. Un número se prueba primero como id y después como código. Un enlace que no es tuyo devuelve 404.

El objeto enlace

{
  "id": 1234,
  "code": "launch",
  "short_url": "https://urlf.ly/launch",
  "destination": "https://example.com/blog/launch-day",
  "title": "Launch post",
  "notes": null,
  "status": "active",
  "clicks": 0,
  "created_at": "2026-11-09 18:00:00",
  "updated_at": "2026-11-09 18:00:00",
  "expires_at": null,
  "encrypted": false
}

status es activo o desactivado. short_url usa tu dominio propio cuando el enlace está en uno. expires_at es null en un enlace que no caduca.

Listar enlaces

GET /links?page=1&per_page=20. page empieza en 1. per_page vale 20 por defecto; el máximo es 100.

{
  "items": [ { "id": 1234, "code": "launch", "...": "..." } ],
  "page": 1,
  "per_page": 20,
  "total": 1
}

Crear un enlace

curl -X POST https://urlf.ly/api/v1/links \
  -H "Authorization: Bearer uf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/blog/launch-day", "title": "Launch post"}'

Devuelve 201:

{
  "id": 1234,
  "code": "aB3xY9",
  "short_url": "https://urlf.ly/aB3xY9",
  "destination": "https://example.com/blog/launch-day",
  "created_at": "2026-11-09 18:00:00"
}

Si ya tienes un enlace activo a exactamente la misma URL, se devuelve ese enlace en lugar de uno nuevo, aunque envíes un alias.

Campos para crear y actualizar

Las demás opciones, como el direccionamiento por país o la ocultación, se configuran en el panel; la API no las cambia.

Obtener un enlace

curl -H "Authorization: Bearer uf_YOUR_API_KEY" https://urlf.ly/api/v1/links/launch

Devuelve 200 con el objeto enlace.

Actualizar un enlace

Envía solo los campos que quieras cambiar. Los que no envíes conservan su valor actual. null borra title, notes o tags.

curl -X PATCH https://urlf.ly/api/v1/links/launch \
  -H "Authorization: Bearer uf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/blog/launch-day-updated"}'

Devuelve 200 con el objeto enlace actualizado.

Borrar un enlace

curl -X DELETE -H "Authorization: Bearer uf_YOUR_API_KEY" https://urlf.ly/api/v1/links/launch

Devuelve 204 sin cuerpo. El enlace corto deja de funcionar.

Estadísticas de un enlace

curl -H "Authorization: Bearer uf_YOUR_API_KEY" https://urlf.ly/api/v1/links/launch/stats

{
  "link_id": 1234,
  "code": "launch",
  "clicks_total": 2,
  "unique_visitors": 2,
  "qr_scans": 1,
  "last_7_days": [
    { "day": "2026-11-03", "clicks": 0 },
    "... one entry per day ...",
    { "day": "2026-11-09", "clicks": 2 }
  ],
  "top_countries": [ { "code": "US", "label": "United States", "clicks": 2 } ],
  "top_referrers": [ { "label": "news.example.org", "clicks": 1 } ]
}

Las cifras de arriba son un ejemplo. clicks_total, unique_visitors y qr_scans cubren toda la vida del enlace. last_7_days tiene una entrada por día UTC, hoy incluido. top_countries (hasta 15) y top_referrers (hasta 10) cubren esos mismos 7 días. Los bots conocidos no se cuentan.

Errores

Los errores devuelven JSON con un único mensaje error (en inglés), por ejemplo {"error": "url is required"}.

Webhooks

Para recibir un aviso cuando un enlace se crea, cambia, borra o recibe un clic, añade un webhook desde tu panel en lugar de consultar la API una y otra vez. Webhooks: plan Premium.