REST API · v1

Documentación de la API

Acorta enlaces, obtén analíticas y gestiona URLs mediante programación. Todos los endpoints devuelven JSON y requieren un token Bearer.

Obtener acceso gratuito a la API

URL base: https://urlly.me/api/v1

POST

/api/v1/shorten

Acortar una URL

GET

/api/v1/stats/{hash}

Obtener analíticas del enlace

GET

/api/v1/links

Listar todos tus enlaces

—

domain_id param

Usar un dominio personalizado

Autenticación

Envía tu token en la cabecera Authorization en cada solicitud

Cabecera	Valor
Authorization	Bearer <token>
Accept	application/json
Content-Type	application/json (Solo POST)

Genera tokens desde tu Configuración de API. Los tokens se muestran solo una vez — guárdalos de forma segura. Los tokens faltantes o inválidos devuelven 401 Unauthorized.

bash

# Save your token in an environment variable
export URLLY_TOKEN="your_token_here"

# Include it in every request
curl https://urlly.me/api/v1/shorten \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

POST /api/v1/shorten 201 Created

Acorta una URL. Opcionalmente proporciona un alias personalizado (3–20 caracteres) y un dominio personalizado verificado.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Notas
long_url	string	Sí	URL válida, máx. 2048 caracteres
custom_alias	string	No	[a-z0-9_-], 3–20 caracteres
domain_id	integer	No	ID de un dominio personalizado verificado. Omítelo para usar el dominio predeterminado.

Respuesta

201 Created

{
  "success": true,
  "short_url": "https://urlly.me/my-link",
  "original_url": "https://example.com/...",
  "hash": "my-link",
  "created_at": "2026-03-19T10:00:00+00:00"
}

Solicitud de ejemplo

bash

# Auto-generated short code
curl -X POST \
  "https://urlly.me/api/v1/shorten" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"long_url":"https://example.com/long-page"}'

# With custom alias
curl -X POST \
  "https://urlly.me/api/v1/shorten" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com/long-page",
    "custom_alias": "my-link"
  }'

GET /api/v1/stats/{hash} 200 OK

Analíticas de clics de un enlace tuyo — clics totales, desglose diario, tipos de dispositivos, principales navegadores.

Parámetro de URL

Parámetro	Descripción
hash	El código corto o alias personalizado de tu enlace

Respuesta

200 OK

{
  "success": true,
  "hash": "aBcDeFg",
  "short_url": "https://urlly.me/aBcDeFg",
  "original_url": "https://example.com",
  "is_active": true,
  "stats": {
    "total_clicks": 142,
    "clicks_by_day": [
      { "date": "2026-03-19", "total": 108 }
    ],
    "devices": { "desktop": 80, "mobile": 62 },
    "browsers": { "Chrome": 95, "Safari": 47 }
  }
}

Solicitud de ejemplo

bash

curl -X GET \
  "https://urlly.me/api/v1/stats/aBcDeFg" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Accept: application/json"

GET /api/v1/links 200 OK · Paginated

Lista paginada de todos tus enlaces, más recientes primero. 20 elementos por página.

Parámetros de consulta

Parámetro	Por defecto	Descripción
page	1	Número de página

Respuesta

200 OK

{
  "success": true,
  "data": [
    {
      "hash": "aBcDeFg",
      "short_url": "https://urlly.me/aBcDeFg",
      "original_url": "https://example.com",
      "clicks": 142,
      "is_active": true,
      "created_at": "2026-03-19T10:00:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 20,
    "total": 58
  }
}

Solicitud de ejemplo

bash

# First page
curl -X GET \
  "https://urlly.me/api/v1/links" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Accept: application/json"

# Page 2
curl -X GET \
  "https://urlly.me/api/v1/links?page=2" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Accept: application/json"

Dominios personalizados

Sirve enlaces cortos desde tu propio dominio en lugar del predeterminado

Los usuarios autenticados pueden añadir dominios personalizados verificados. Una vez verificado, pasa domain_id al endpoint POST /shorten para crear enlaces cortos bajo ese dominio.

Cómo configurar

1.Ve a Dominios personalizados en tu panel de control y añade tu dominio.
2.Añade un registro DNS CNAME apuntando tu subdominio a urlly.me.
3.Añade el registro TXT de verificación mostrado en el panel y haz clic en Verificar.
4.Una vez verificado, anota el id del dominio y pásalo como domain_id en las llamadas API.

Los códigos cortos son únicos por dominio. El mismo alias puede existir en tu dominio personalizado y en el predeterminado simultáneamente.

Ejemplo: acortar con dominio personalizado

bash

# Shorten using your custom domain (id: 3)
curl -X POST \
  "https://urlly.me/api/v1/shorten" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com/long-page",
    "domain_id": 3
  }'

# Response — short_url uses your domain
{
  "success": true,
  "short_url": "https://links.yourdomain.com/aBcDeFg",
  "original_url": "https://example.com/long-page",
  "hash": "aBcDeFg",
  "created_at": "2026-03-21T10:00:00+00:00"
}

Límite de peticiones

2000 solicitudes por 1 min por token

Cabecera de respuesta	Descripción
X-RateLimit-Limit	Máx. solicitudes por ventana (2000)
X-RateLimit-Remaining	Solicitudes restantes en esta ventana
Retry-After	Segundos hasta el reinicio de ventana (solo 429)

Al superarse, las solicitudes devuelven 429 Too Many Requests. Consulta Retry-After para saber cuándo reintentar.

Respuesta 429

429 Too Many Requests

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 0
Retry-After: 47

{
  "message": "Too Many Attempts."
}

Códigos de error

Todos los errores devuelven JSON con un campo message. Los errores de validación (422) incluyen también un objeto errors.

Estado	Significado	Causa común
401	No autorizado	Token faltante o inválido
403	Prohibido	El recurso no te pertenece
404	No encontrado	El hash del enlace no existe
422	Error de validación	Campos inválidos o alias duplicado
429	Demasiadas solicitudes	Límite de peticiones excedido
500	Error del servidor	Algo salió mal en nuestro lado

Ejemplos de respuestas de error

JSON

# 401 Unauthorized
{ "message": "Unauthenticated." }

# 404 Not Found
{
  "error": "not_found",
  "message": "Link not found or does not belong to you."
}

# 422 Validation Error
{
  "message": "The long_url field is required.",
  "errors": {
    "long_url": [ "The long_url field is required." ]
  }
}

# 422 Unsafe URL
{
  "error": "unsafe_url",
  "message": "This URL has been flagged as unsafe."
}

¿Listo para construir?

Genera un token y realiza tu primera llamada a la API en segundos.

Crear cuenta gratuita Iniciar sesión