API de enlaces

La API crea enlaces cortos anónimos, devuelve sus estadísticas de clics, cambia sus ajustes y los borra. Las peticiones y las respuestas usan JSON. CORS está habilitado, así que las llamadas funcionan también desde código del navegador.

Dirección base:

http://anonym.es/api/v1

Inicio rápido

Para crear un enlace corto, envía la dirección de destino:

curl -X POST http://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

Con un token de cuenta la misma llamada guarda el enlace en tu panel y lo cuenta en la cuota de tu plan:

curl -X POST http://anonym.es/api/v1/links \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

La respuesta contiene la dirección corta, el id del enlace y el token que gestiona este enlace. Guarda el token: hará falta para leer o borrar el enlace más adelante.

{
  "ok": true,
  "link": {
    "id": 4821,
    "short": "http://anonym.es/k7m2q",
    "url": "https://example.com/article",
    "status": "active",
    "password": false,
    "created_at": "2026-09-05T14:02:11Z",
    "expires_at": null,
    "max_hits": null,
    "self_destruct": false,
    "delay": null,
    "no_countdown": false,
    "adult": false,
    "note": null,
    "tags": [],
    "clicks": 0,
    "uniques": 0
  },
  "token": "3f9c1b7e2d4a4c0e9b8f7a6d5c4b3a21",
  "left": 4
}

Campos del objeto enlace

Todos los endpoints que devuelven un enlace usan esta estructura. Las marcas de tiempo son ISO 8601 en UTC. Los contadores clicks y uniques abarcan toda la vida del enlace.

Autorización

Las peticiones autorizadas llevan el token en la cabecera Authorization. Como alternativa se acepta la cabecera X-API-Key. Los tokens nunca se pasan en la query string.

Authorization: Bearer YOUR_TOKEN

Un token de cuenta empieza por anon_. Un token de enlace consta de 32 caracteres. Generar un nuevo token de cuenta invalida el anterior.

Ejemplo:

curl http://anonym.es/api/v1/me \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Generar un token de cuenta en el panel

Endpoints

El cuerpo de la petición puede enviarse como application/json o como application/x-www-form-urlencoded. Los nombres de los parámetros y los códigos de error son idénticos en todos los endpoints.

El coste se indica en unidades del límite de ritmo, véase Límites de ritmo.

Crear un enlace

POST /api/v1/links

La petición mínima contiene solo el campo url:

curl -X POST http://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

Con un token de cuenta el enlace pertenece a la cuenta y se cuenta en la cuota de su plan. Sin token es un enlace de invitado en la cuota de la IP:

curl -X POST http://anonym.es/api/v1/links \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

Una petición correcta devuelve el estado 201 junto con el enlace, su token y el número de enlaces que quedan en el periodo de cuota actual.

Campos de la respuesta:

Enlace con nombre propio

La dirección corta recibe el nombre my-article si está libre y cumple las reglas siguientes.

curl -X POST http://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article","name":"my-article"}'

Reglas de los nombres:

• Letras latinas, dígitos, guion y guion bajo. Desde 5 caracteres en el plan Free y desde 3 en los planes de pago, hasta 32. No se distinguen mayúsculas: Promo y promo son el mismo enlace.
• Los nombres de páginas, los códigos de idioma y las palabras de servicio están reservados.
• Se rechazan los nombres de marcas y las palabras ofensivas. Los nombres pasan por una lista de palabras y una revisión automática. El número de nombres propios por hora está limitado según el plan.
• Un nombre ocupado devuelve el estado 409 con alternativas libres en suggest.
• Un nombre de subdominio (sub: true, plan Max) es una etiqueta DNS: letras, dígitos y guiones, sin guion en los extremos ni guion bajo. Nombres como www, mail o ns1 están reservados.

Un nombre puede comprobarse antes de crear el enlace:

curl "http://anonym.es/api/v1/names/check?name=my-article"

Campos de la respuesta de comprobación:

Varios enlaces a la vez

El campo urls acepta hasta 50 direcciones, como array JSON o como texto con una dirección por línea. Cada dirección se convierte en su propio enlace con su propio token, y los demás campos se aplican a todos. El nombre propio no está disponible en un lote.

curl -X POST http://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com/a","https://example.com/b","https://example.com/c"]}'

La respuesta contiene batch: true y un array results con una entrada por dirección, en el orden enviado. Una dirección defectuosa produce una entrada con ok: false y el código de error sin detener el resto.

Ajustes adicionales

curl -X POST http://anonym.es/api/v1/links \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "name": "my-article",
    "expires_days": 30,
    "max_hits": 1000,
    "self_destruct": true,
    "password": "secret",
    "note": "Available until the end of the month",
    "delay": 5,
    "tags": "blog,promo",
    "qr": true,
    "qr_size": 300,
    "qr_format": "png"
  }'

Las opciones marcadas como de pago se ignoran para invitados y en el plan Free. La respuesta refleja los ajustes que el enlace recibió realmente.

Listar enlaces

GET /api/v1/links

Requiere un token de cuenta. Los enlaces se devuelven de más nuevo a más antiguo.

curl "http://anonym.es/api/v1/links?page=1&per=50" \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

La búsqueda y el filtro por etiqueta pueden combinarse:

curl "http://anonym.es/api/v1/links?q=example&tag=promo" \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Campos de la respuesta:

Buscar un enlace por su dirección corta

Un enlace se identifica por su id numérico (el campo id, por ejemplo 4821), no por el nombre de la dirección corta. Cuando solo se conoce la dirección corta, el id puede obtenerse con cualquier token que gestione ese enlace:

curl --get http://anonym.es/api/v1/links/lookup \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "short=http://anonym.es/k7m2q"

Detalles del enlace y estadísticas

GET /api/v1/links/{id}

Devuelve los ajustes del enlace, su estado, el número de visitas y el número de visitantes únicos durante toda su vida:

curl http://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer YOUR_TOKEN"

Con un token de cuenta, el parámetro stats añade un informe de visitas:

curl "http://anonym.es/api/v1/links/4821?stats=day" \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Campos de la respuesta: stats

Editar un enlace

PATCH /api/v1/links/{id}

Solo cambian los campos enviados:

curl -X PATCH http://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"max_hits": 2000, "delay": 3, "tags": "blog,updated"}'

Vaciar un valor

• password, note y tags: una cadena vacía elimina el valor.
• expires_days y max_hits: null, una cadena vacía o 0 quitan el límite. self_destruct se desactiva cuando no queda ni límite ni duración.
• delay: null o una cadena vacía restauran el valor por defecto del plan. 0 significa redirección inmediata.
• url no puede vaciarse, y un enlace de solo nota sigue necesitando una nota.

curl -X PATCH http://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password": "", "note": "", "expires_days": null, "max_hits": null, "delay": 0}'

Borrar un enlace

DELETE /api/v1/links/{id}

curl -X DELETE http://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer YOUR_TOKEN"

Tras el borrado, el nombre propio vuelve a quedar libre. Las estadísticas se borran junto con el enlace.

Campos de la respuesta:

Código QR

Para una etiqueta img de HTML, solicita el código por la dirección corta. Este endpoint no necesita token: la propia dirección corta es la clave, y cualquiera que la tenga puede generar el mismo código.

<img
  src="http://anonym.es/api/v1/qr?short=http%3A%2F%2Fanonym.es%2Fk7m2q&qr_size=400"
  alt="QR code"
>

El código del lado del servidor también puede solicitar la imagen por id con un token, o recibirla en JSON codificada en base64 añadiendo qr=true a la llamada de creación o de detalles:

curl "http://anonym.es/api/v1/links/4821/qr?qr_size=400&qr_format=svg" \
  -H "Authorization: Bearer YOUR_TOKEN" -o qr.svg

Parámetros de ambos endpoints de imagen:

El miembro qr en las respuestas JSON:

Detalles de la cuenta

GET /api/v1/me

Requiere un token de cuenta. Devuelve el plan, sus límites y la cuota restante:

curl http://anonym.es/api/v1/me \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Errores

Los errores se devuelven en un único formato JSON:

{
  "ok": false,
  "error": "taken",
  "message": "This name is already taken.",
  "field": "name",
  "suggest": ["my-article-26", "my-my-article", "my-article-link"]
}

field contiene el nombre del parámetro incorrecto, o null cuando el error no se refiere a un campo concreto. Un nombre ocupado añade suggest, una opción de pago añade upgrade, las cuotas y los límites de ritmo añaden la cabecera Retry-After.

Límites de ritmo

Cada llamada cuesta unidades y cada plan dispone de un presupuesto de unidades por minuto (véase Planes y límites). Una lectura cuesta 1 unidad, una página de lista 2, un código QR 3, una edición 3, un borrado 2, una creación 5 más 1 por dirección. Cada respuesta lleva estas cabeceras:

Planes y límites

Los límites exactos de cada plan. Los enlaces se cuentan por día y dirección IP en Free, y por mes y cuenta en los planes de pago. La última columna enumera los ajustes que puede usar cada plan.

Especificación OpenAPI

La descripción técnica completa como documento OpenAPI 3.1: http://anonym.es/api/v1/openapi.json

Contiene esquemas y ejemplos de todas las peticiones y respuestas, los límites de los planes, las reglas de los nombres y los códigos de error. Sirve para Swagger UI, Postman, Insomnia y generadores de clientes.