API

Создавайте короткие ссылки и управляйте ими из скриптов и приложений. API бесплатен. Создайте ключ в панели управления в разделе Ключи API и отправляйте его как токен Bearer.

Аутентификация

Authorization: Bearer gz_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ключ показывается один раз. Относитесь к нему как к паролю: любой, у кого он есть, может создавать и изменять ссылки в вашем аккаунте. Утёкший ключ отзовите в панели управления.

Ограничения

• 60 запросов в минуту на один ключ.
• 500 новых ссылок в день на один аккаунт.
• Адреса назначения проверяются через Google Safe Browsing и наш чёрный список. Другие сокращатели ссылок нельзя использовать как адрес назначения.

Создать ссылку

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 необязателен (4–32 знака: буквы, цифры, - или _). Опустите его, чтобы получить случайный код из 7 знаков. Ответ 201:

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

Список ссылок

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

Сначала новые. Передайте nextCursor с предыдущей страницы, чтобы получить следующую. clicks=1 добавляет счётчики кликов людей за всё время.

Получить, изменить, удалить

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

Аналитика

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

Возвращает клики людей за последние 90 дней и за всё время, клики по дням, а также топ стран, источников, устройств, браузеров и операционных систем. Боты и превью ссылок (Slack, WhatsApp и подобные) считаются отдельно в botClicks. Результаты кешируются примерно на 5 минут.

Ошибки

Ошибки возвращаются с кодом состояния HTTP и телом в JSON:

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

• 400 неверные данные (invalid_url, invalid_slug, …)
• 401 ключ отсутствует, неверен или отозван
• 409 такой адрес уже занят
• 422 адрес назначения не разрешён (destination_blocked)
• 429 достигнут лимит частоты или дневной лимит

Машиночитаемое описание всех эндпоинтов — по адресу /openapi.json.