API

Crea y gestiona enlaces cortos desde scripts y aplicaciones. La API es gratuita. Crea una clave en tu panel, en Claves de API, y envíala como token bearer.

Autenticación

Authorization: Bearer gz_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Las claves se muestran una sola vez. Trátalas como contraseñas: cualquiera que tenga tu clave puede crear y editar enlaces en tu cuenta. Revoca desde el panel cualquier clave filtrada.

Límites

60 peticiones por minuto y clave.
500 enlaces nuevos al día por cuenta.
Los destinos se comprueban con Google Safe Browsing y con nuestra lista de bloqueo. No se pueden usar otros acortadores de enlaces como destino.

Crear un enlace

curl -X POST https://gozi.to/api/my/links \
  -H "Authorization: Bearer $GOZI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/launch", "code": "launch"}'

code es opcional (4–32 letras, números, - o _). Omítelo para obtener un código aleatorio de 7 caracteres. Respuesta 201:

{
  "link": {
    "code": "launch",
    "shortUrl": "https://gozi.to/launch",
    "url": "https://example.com/launch",
    "status": "active",
    "statusReason": null,
    "custom": true,
    "createdAt": 1790000000000,
    "expiresAt": null
  }
}

Listar enlaces

GET /api/my/links?limit=25&cursor=<nextCursor>&q=<search>&clicks=1

Del más reciente al más antiguo. Pasa el nextCursor de la página anterior para obtener la siguiente. clicks=1 añade el total histórico de clics humanos.

Obtener, editar, eliminar

GET    /api/my/links/{code}
PATCH  /api/my/links/{code}   {"url": "https://new.example"}  or  {"status": "disabled" | "active"}
DELETE /api/my/links/{code}

Analítica

GET /api/my/links/{code}/stats

Devuelve los clics humanos de los últimos 90 días y de todo el tiempo, los clics por día y los principales países, referentes, dispositivos, navegadores y sistemas operativos. Los bots y las vistas previas de enlaces (Slack, WhatsApp, etc.) se cuentan aparte en botClicks. Los resultados se guardan en caché unos 5 minutos.

Errores

Los errores usan códigos de estado HTTP y un cuerpo JSON:

{ "error": { "code": "slug_taken", "message": "That custom link is already taken." } }

400 entrada no válida (invalid_url, invalid_slug, …)
401 clave ausente, no válida o revocada
409 el enlace personalizado ya está ocupado
422 destino no permitido (destination_blocked)
429 límite de frecuencia o límite diario alcanzado

En /openapi.json hay una descripción legible por máquina de todos los endpoints.