API ссылок

API создаёт анонимные короткие ссылки, возвращает статистику переходов, изменяет настройки и удаляет ссылки. Запросы и ответы передаются в формате JSON. CORS включён, поэтому вызовы работают и из кода в браузере.

Базовый адрес:

http://anonym.es/api/v1

Быстрый старт

Чтобы создать короткую ссылку, отправьте адрес назначения:

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

С токеном аккаунта тот же вызов помещает ссылку в ваш кабинет и учитывает её в квоте тарифа:

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"}'

Ответ содержит короткий адрес, идентификатор ссылки и токен управления этой ссылкой. Сохраните токен: он понадобится, чтобы позже прочитать или удалить ссылку.

{
  "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
}

Поля объекта ссылки

Все эндпоинты, возвращающие ссылку, используют эту структуру. Время указано в формате ISO 8601 в UTC. Счётчики clicks и uniques охватывают весь срок жизни ссылки.

Авторизация

Авторизованные запросы передают токен в заголовке Authorization. Как альтернатива принимается заголовок X-API-Key. В строке запроса токены не передаются.

Authorization: Bearer YOUR_TOKEN

Токен аккаунта начинается с anon_. Токен ссылки состоит из 32 символов. Создание нового токена аккаунта отменяет предыдущий.

Пример:

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

Создать токен аккаунта в личном кабинете

Эндпоинты

Тело запроса передаётся как application/json или application/x-www-form-urlencoded. Имена параметров и коды ошибок одинаковы для всех эндпоинтов.

Стоимость указана в единицах лимита запросов, см. раздел «Лимиты запросов».

Создание ссылки

POST /api/v1/links

Минимальный запрос содержит только поле url:

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

С токеном аккаунта ссылка принадлежит аккаунту и учитывается в квоте тарифа. Без токена это гостевая ссылка в квоте 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"}'

Успешный запрос возвращает статус 201 вместе со ссылкой, её токеном и числом ссылок, оставшихся в текущем периоде квоты.

Поля ответа:

Ссылка с собственным именем

Короткий адрес получит имя my-article, если оно свободно и соответствует правилам ниже.

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

Правила имён:

• Латинские буквы, цифры, дефис и подчёркивание. От 5 символов на тарифе Free и от 3 на платных тарифах, не более 32. Регистр не учитывается: Promo и promo считаются одной ссылкой.
• Имена страниц сайта, коды языков и служебные слова зарезервированы.
• Названия брендов и оскорбительные слова отклоняются. Имена проходят проверку по списку слов и автоматическую модерацию. Число собственных имён в час ограничено тарифом.
• Занятое имя возвращает статус 409 со свободными вариантами в поле suggest.
• Имя сабдомена (sub: true, тариф Max) состоит из одной DNS-метки: буквы, цифры и дефисы, без дефиса по краям и без подчёркивания. Имена вида www, mail или ns1 зарезервированы.

Имя можно проверить до создания ссылки:

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

Поля ответа проверки:

Несколько ссылок за один запрос

Поле urls принимает до 50 адресов в виде JSON-массива или текста с одним адресом в строке. Каждый адрес становится отдельной ссылкой со своим токеном, а остальные поля применяются ко всем. Собственное имя в пакете недоступно.

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"]}'

Ответ содержит batch: true и массив results с записью на каждый адрес в порядке отправки. Ошибочный адрес даёт запись с ok: false и кодом ошибки, не прерывая остальные.

Дополнительные настройки

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"
  }'

Опции, отмеченные как платные, игнорируются для гостей и на тарифе Free. Ответ отражает настройки, которые ссылка получила фактически.

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

GET /api/v1/links

Требуется токен аккаунта. Ссылки возвращаются от новых к старым.

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

Поиск и фильтр по тегу можно сочетать:

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

Поля ответа:

Поиск ссылки по короткому адресу

Ссылка адресуется числовым идентификатором (поле id, например 4821), а не именем из короткого адреса. Если известен только короткий адрес, идентификатор можно получить любым токеном, который управляет этой ссылкой:

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

Сведения о ссылке и статистика

GET /api/v1/links/{id}

Возвращает настройки ссылки, её состояние, число переходов и число уникальных посетителей за всё время:

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

С токеном аккаунта параметр stats добавляет отчёт о переходах:

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

Поля ответа: stats

Изменение ссылки

PATCH /api/v1/links/{id}

Изменяются только переданные поля:

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"}'

Сброс значения

• password, note и tags: пустая строка удаляет значение.
• expires_days и max_hits: null, пустая строка или 0 снимают ограничение. self_destruct отключается, когда не остаётся ни лимита, ни срока.
• delay: null или пустая строка возвращают значение тарифа по умолчанию. 0 означает мгновенный переход.
• url нельзя сделать пустым, а ссылке-заметке по-прежнему нужна заметка.

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}'

Удаление ссылки

DELETE /api/v1/links/{id}

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

После удаления собственное имя снова становится свободным. Статистика удаляется вместе со ссылкой.

Поля ответа:

QR-код

Для HTML-тега img запрашивайте код по короткому адресу. Этот эндпоинт не требует токена: ключом служит сам короткий адрес, и любой, кто его знает, может получить такой же код.

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

Серверный код может также запросить изображение по идентификатору с токеном или получить его в JSON в кодировке base64, добавив qr=true к запросу создания или сведений:

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

Параметры обоих эндпоинтов изображения:

Поле qr в ответах JSON:

Сведения об аккаунте

GET /api/v1/me

Требуется токен аккаунта. Возвращает тариф, его ограничения и остаток квоты:

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

Ошибки

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

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

field содержит имя некорректного параметра или null, если ошибка не относится к конкретному полю. Занятое имя добавляет suggest, платная опция добавляет upgrade, квоты и лимиты частоты добавляют заголовок Retry-After.

Лимиты частоты

Каждый вызов стоит единицы, а у каждого тарифа есть бюджет единиц в минуту (см. «Тарифы и ограничения»). Чтение стоит 1 единицу, страница списка 2, QR-код 3, редактирование 3, удаление 2, создание 5 плюс 1 за каждый адрес. Каждый ответ содержит заголовки:

Тарифы и ограничения

Точные ограничения каждого тарифа. Ссылки считаются за сутки на IP-адрес на Free и за месяц на аккаунт на платных тарифах. Последний столбец перечисляет настройки, доступные тарифу.

Спецификация OpenAPI

Полное техническое описание в виде документа OpenAPI 3.1: http://anonym.es/api/v1/openapi.json

Документ содержит схемы и примеры всех запросов и ответов, ограничения тарифов, правила имён и коды ошибок. Подходит для Swagger UI, Postman, Insomnia и генераторов клиентов.