Referencia de API

Autenticación

Envía la clave como bearer token en cada solicitud.

Crear un enlace

Crea un enlace corto nuevo. El destino pasa por el filtro antifraude al crearse; la escritura es más lenta que en un acortador normal.

curl -X POST https://urlvis.com/api/links \
  -H "Authorization: Bearer urlvis_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://example.com/campaign",
    "domainId": "<domain-uuid>",
    "slug": "spring",
    "expiresAt": "2026-12-31T23:59:00.000Z"
  }'

destination, domainId — required · slug, expiresAt — optional

Listar enlaces

Devuelve todos los enlaces de tu cuenta.

curl https://urlvis.com/api/links \
  -H "Authorization: Bearer urlvis_live_..."

Cambiar el destino de un enlace

Actualiza adónde apunta un enlace existente. El enlace corto, su código QR y el historial de clics permanecen iguales. El nuevo destino pasa por la misma comprobación de seguridad que un enlace nuevo, por lo que puede devolver 422 blocked_by_filter.

curl -X PATCH https://urlvis.com/api/links/<link-id> \
  -H "Authorization: Bearer urlvis_live_..." \
  -H "Content-Type: application/json" \
  -d '{"destination": "https://example.com/new-target"}'

destination — required · utm — optional. The short link, its QR code and click history stay the same. The new destination runs through the same security scan as a new link, so this can return 422 blocked_by_filter.

Eliminar un enlace

Elimina un enlace de tu cuenta. Devuelve 204 en caso de éxito, 404 si no existe.

curl -X DELETE https://urlvis.com/api/links/<link-id> \
  -H "Authorization: Bearer urlvis_live_..."

204 on success, 404 if no such link exists on your account.

Exportar analítica

Exporta las estadísticas de clics como CSV. Filtrado opcional por linkId. La retención de datos depende de tu plan.

curl "https://urlvis.com/api/analytics/export?linkId=<link-uuid>" \
  -H "Authorization: Bearer urlvis_live_..." \
  -o analytics.csv

Límites de uso

Cada respuesta indica tu cuota restante. Los límites son por clave, no por dirección IP.

X-RateLimit-Limit: 60       # links:write
X-RateLimit-Limit: 600      # links:read
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 42        # seconds
Retry-After: 42              # 429 only

Errores

Los errores se devuelven en JSON con un campo error y el estado HTTP correspondiente.

401 invalid_api_key      key unknown, revoked, or plan no longer includes API
403 insufficient_scope   key lacks the scope this endpoint needs
404 not_found            no such link on this account
422 blocked_by_filter    destination rejected by the fraud filter
402 link_quota           monthly plan quota exhausted
429 rate_limited         see Retry-After

Obtener tu ID de dominio

El endpoint POST /api/links requiere un domainId. Actualmente no hay un endpoint de API para listar tus dominios — el endpoint de domains requiere sesión del panel. Para obtener tu ID de dominio:

1. Abre el panel y ve a Dominios.
2. Cada tarjeta de dominio muestra su ID con un botón de copia al lado — cópialo desde ahí.