Создавайте и редактируйте короткие ссылки и следите за их статистикой прямо из своего кода. REST API с JSON на входе и на выходе, отдельный ключ для каждой интеграции, а каждый эндпоинт описан здесь с примером запроса и реальным ответом.
API pik.li позволяет вашим программам делать то же, что и панель управления: создавать и редактировать короткие ссылки, получать их статистику, просматривать ваши теги и домены и управлять вебхуками. API работает по HTTPS, и все пути начинаются с базового URL, указанного выше.
Content-Type: application/json; параметры запросов GET передаются в строке запроса. Ответы всегда приходят в JSON в кодировке UTF-8 — кроме QR-кода, который возвращается изображением./api/v1), и каждый ответ содержит заголовок X-Api-Version: 1. Со временем в ответах v1 могут появляться новые поля: пусть ваш код просто игнорирует незнакомые.2026-09-23T10:15:42.118+02:00); даты без времени выглядят так: 2026-09-23.GET /links/lookup.GET /me возвращает ваш аккаунт и план.POST /links.export PIKLI_KEY="pk_live_…"
curl https://pik.li/api/v1/me \
-H "Authorization: Bearer $PIKLI_KEY"
curl -X POST https://pik.li/api/v1/links \
-H "Authorization: Bearer $PIKLI_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/a/very/long/page"}'Для каждого вызова, кроме GET /ping, нужен ключ API. Он передаётся в заголовке Authorization как bearer-токен.
Authorization: Bearer pk_live_3kZ9vQeX1mT0bR7yNw2aLp4sUc8dHf6JПодойдёт и заголовок X-API-Key. Параметр запроса api_key всё ещё принимается ради старых клиентов, но лучше его не использовать: адреса запросов попадают в логи и в историю браузера.
Ключи начинаются с pk_live_, за которым следуют 32 символа. Ключ видит ровно то же, что и его аккаунт, — ссылки, домены, теги, статистику и вебхуки, — и у всех ключей одного аккаунта одинаковые права: ключей только для чтения нет.
401 unauthorized.API входит в платные планы (Premium и Business). В план Base он не входит, если только команда pik.li не включит его для бесплатного плана или для вашего аккаунта. В любом случае у аккаунта должен быть подтверждённый e-mail, и он не должен быть заблокирован или приостановлен.
Если какое-то из этих условий не выполнено, API отвечает api_disabled, email_unconfirmed или account_blocked.
Это стандартные значения каждого плана, взятые напрямую из текущих настроек цен. Ваши собственные значения — с учётом изменений, которые команда внесла для вашего аккаунта, — возвращают GET /limits и GET /me.
Каждый ключ может выполнить определённое число запросов в минуту, которое зависит от плана (см. таблицу выше). Счётчик обнуляется в начале каждой минуты.
X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-ResetRetry-AfterПри превышении лимита API отвечает 429 с ошибкой rate_limited и заголовком Retry-After. Подождите указанное время и продолжайте: немедленные повторы только съедают лимит следующей минуты.
HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Retry-After: 18
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790151360
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Check the X-RateLimit-* headers and retry after the window resets.",
"details": { "limit": 600, "period_seconds": 60, "resets_at": "2026-09-23T08:16:00Z" },
"docs_url": "https://pik.li/help#error-rate_limited"
},
"request_id": "2b8e51d0-7a4c-4f1e-9d3b-5c6a0e8f7d21"
}На неудачный запрос всегда приходит ответ одинаковой структуры, для любого эндпоинта, с HTTP-статусом, соответствующим проблеме.
{
"error": {
"code": "quota_exceeded",
"message": "Link quota reached: 2500 links per month on your plan.",
"details": { "limit": 2500, "used": 2500, "period": "month", "resets_at": "2026-09-30T22:00:00Z" },
"docs_url": "https://pik.li/help#error-quota_exceeded"
},
"request_id": "6f1c2a9e-4b0d-4c55-9a51-8f2f0d7c1e3b"
}codemessagedetailsdocs_urlrequest_idЛюбой эндпоинт, которому нужен ключ, может также ответить unauthorized account_blocked email_unconfirmed api_disabled rate_limited: в описании каждого эндпоинта они не повторяются.
account_blocked403email_unconfirmed403api_disabled403forbidden403feature_required402quota_exceeded402not_found404link_blocked409conflict409invalid422domain_not_allowed422bad_request400invalid_json400invalid_parameter400bulk_empty400bulk_too_many400idempotency_key_invalid400rate_limited429Ответ 500 означает, что что-то сломалось на нашей стороне и исправлять в вашем запросе нечего. Повторите попытку чуть позже; если ошибка не исчезает, напишите в поддержку и укажите значение заголовка X-Request-Id.
Списки, которые могут быть длинными, разбиты на страницы: GET /links, GET /links/active и GET /links/:id/clicks.
page: нужная страница, начиная с 1.per_page: сколько элементов на странице, от 1 до 100 (по умолчанию 50). limit принимается как синоним.Ответ содержит объект pagination, а общее количество также приходит в заголовке X-Total-Count. Запрашивайте next_page, пока он не станет null.
{
"links": [],
"pagination": { "page": 2, "per_page": 50, "total": 137, "total_pages": 3, "next_page": 3, "prev_page": 1 }
}POST /links, POST /links/bulk и POST /links/generate принимают заголовок Idempotency-Key: произвольный текст длиной до 128 символов, который вы выбираете сами, — свой для каждой операции, например номер заказа или UUID.
Если тот же Idempotency-Key снова приходит с того же ключа API в течение 24 часов, pik.li ничего не создаёт, а возвращает первый ответ с заголовком Idempotent-Replayed: true. Так запрос, повторённый после тайм-аута, никогда не создаёт дубликат.
HTTP/1.1 201 Created
Idempotent-Replayed: true
Content-Type: application/json; charset=utf-8Ответы со статусом 5xx не запоминаются, поэтому повтор запроса с тем же ключом выполнит его заново. На слишком длинный ключ приходит idempotency_key_invalid.
Сообщения об ошибках доступны на девяти языках: en it zh ar ru fr de es pt-BR. API выбирает язык по параметру locale, затем по заголовку Accept-Language, затем по языку вашего аккаунта, а если ничего не подошло — использует английский. Меняется только сообщение: коды и имена полей остаются прежними, как и docs_url, который открывает эту страницу на том же языке.
curl "https://pik.li/api/v1/links?status=nope" \
-H "Authorization: Bearer $PIKLI_KEY" \
-H "Accept-Language: it"
{
"error": {
"code": "invalid_parameter",
"message": "Valore non valido per il parametro status.",
"details": { "allowed": ["all", "active", "disabled", "review", "expired"] },
"docs_url": "https://pik.li/help?locale=it#error-invalid_parameter"
},
"request_id": "0d5c9b7e-1f2a-4e3b-8c6d-7a9e0f1b2c3d"
}Эндпоинты статистики берут временное окно и сравнивают его с предыдущим окном той же длины: отсюда и берутся previous и delta_pct.
period24h, 7d, 30d, 90d, 1y или all (вся история, которую хранит ваш план). Подойдёт и число дней: period=45 или устаревший вариант days=45. По умолчанию — 7d для аккаунта, 30d для отдельной ссылки и all для списка кликов.from, to2026-09-01) или время в формате ISO 8601. По умолчанию to — текущий момент, from — за 30 дней до to; дата в to учитывается до конца этого дня.intervalhour или day — шаг временного ряда. Окна до 48 часов по умолчанию разбиваются по часам, более длинные — по дням; почасовой ряд охватывает не больше 7 дней.window.clampedretention_days). Если окно пришлось обрезать, window.clamped равен true.botsbots=1, чтобы считать и их; статистика отдельной ссылки к тому же показывает их отдельно в period.bots.Любой эндпоинт, который возвращает ссылку, возвращает её в таком виде.
idintegershort_urlstringslugstringdomainstringtarget_urlstringtarget_hoststringtitlestring | nulldescriptionstring | nulltagsarraystatusstringmoderationstringactivebooleanexpiredbooleanpassword_protectedbooleanclicksintegerunique_clicksintegerlast_clicked_atstring | nullexpires_atstring | nullmax_clicksinteger | nulldisabled_reasonstring | nullutmobject | nullpreview_urlstringqr_urlstringcreated_atstringupdated_atstringВсе эндпоинты с параметрами, запросом, который можно вставить в терминал, и реальным ответом, сокращённым там, где список получился бы длинным. Примеры берут ключ из $PIKLI_KEY, как в быстром старте.
Работает ли API и сколько осталось от лимитов вашего плана.
/ping
Без ключа
Ключ не нужен: эндпоинт предназначен для проверок доступности. Возвращает время сервера и адреса этой документации и файла OpenAPI.
curl https://pik.li/api/v1/ping{
"ok": true,
"service": "pik.li",
"version": "v1",
"time": "2026-09-23T08:15:42Z",
"docs": "https://pik.li/help",
"openapi": "https://pik.li/openapi.json"
}/limits
Сколько ссылок ещё можно создать сегодня или в этом месяце, отслеженные клики, текущее окно ограничения частоты, используемые ключи и собственные домены, а также максимальный размер пакетного вызова. Все значения учитывают изменения, которые команда могла внести для вашего аккаунта.
curl https://pik.li/api/v1/limits \
-H "Authorization: Bearer $PIKLI_KEY"{
"plan": "premium",
"plan_name": "Premium",
"links": {
"period": "month", "limit": 2500, "used": 412, "remaining": 2088,
"resets_at": "2026-09-30T22:00:00Z",
"today": 9, "this_month": 412, "per_day": 0, "per_month": 2500
},
"clicks": { "limit": 150000, "used": 38120, "remaining": 111880, "resets_at": "2026-09-30T22:00:00Z" },
"rate_limit": { "limit": 600, "remaining": 597, "period_seconds": 60, "resets_at": "2026-09-23T08:16:00Z" },
"api_keys": { "used": 2, "limit": 10 },
"custom_domains": { "used": 1, "limit": 3 },
"bulk": { "max_items": 100 },
"retention_days": 730,
"link_ttl_days": 0,
"features": ["qr", "analytics_full", "tags", "export", "custom_slug", "password", "expiry", "utm", "bulk", "api", "webhooks"]
}Кто выполняет вызов: аккаунт, которому принадлежит ключ.
/me
Профиль, план и срок его действия, функции, лимиты и их использование, а также ключ, который сделал вызов, с его счётчиком запросов.
curl https://pik.li/api/v1/me \
-H "Authorization: Bearer $PIKLI_KEY"{
"id": 1042,
"username": "anna",
"email": "[email protected]",
"name": "Anna Rossi",
"status": "active",
"confirmed": true,
"locale": "it",
"plan": "premium",
"plan_name": "Premium",
"interval": "monthly",
"plan_expires_at": "2026-10-14T23:59:59.000+02:00",
"api_enabled": true,
"features": ["qr", "analytics_full", "tags", "export", "custom_slug", "password", "expiry", "utm", "bulk", "api", "webhooks"],
"limits": {
"links_per_day": 0, "links_per_month": 2500, "clicks_per_month": 150000,
"retention_days": 730, "link_ttl_days": 0, "custom_domains": 3, "api_rpm": 600
},
"usage": {
"links_today": 9, "links_this_month": 412, "clicks_this_month": 38120,
"links_quota_used": 412, "links_quota_limit": 2500, "links_total": 3187
},
"api_key": {
"id": 55, "name": "CRM production", "prefix": "pk_live_Xq3v",
"created_at": "2026-09-02T16:40:10.311+02:00", "last_used_at": "2026-09-23T10:15:42.020+02:00", "requests_count": 18230
},
"created_at": "2026-03-11T09:12:47.664+01:00"
}Создание, поиск, изменение, приостановка и статистика ваших коротких ссылок.
/links
Сначала самые новые, если не выбран другой порядок. Фильтры сочетаются: ссылка должна удовлетворять им всем.
q
string
в строке запроса
Текст для поиска в slug, заголовке и адресе назначения.
tag
string
в строке запроса
Только ссылки с этим тегом.
tags
string
в строке запроса
Только ссылки со всеми перечисленными тегами, через запятую.
domain
string
в строке запроса
Только этот домен, по имени хоста (например, lnkz.li). Домен должен быть одним из ваших: см. GET /domains.
status
string
в строке запроса
all, active, disabled, review или expired.
view
string
в строке запроса
Готовые представления панели управления: active_24h (с кликами за последние 24 часа), created_today, expiring, moderated, review, disabled, expired, protected (с паролем).
within_days
integer
в строке запроса
Вместе с view=expiring: на сколько дней вперёд смотреть, от 1 до 365 (по умолчанию 7).
created_after
string
в строке запроса
Созданные начиная с этой даты или времени (ISO 8601).
created_before
string
в строке запроса
Созданные до этой даты (включая весь день) или до этого времени.
clicked_after
string
в строке запроса
Получившие хотя бы один клик начиная с этой даты или времени.
sort
string
в строке запроса
recent (по умолчанию), oldest, clicks, alpha (по заголовку, затем по slug), expiring (сначала те, что истекают раньше, только ссылки со сроком действия), last_clicked.
page
integer
в строке запроса
Номер страницы, начиная с 1.
per_page
integer
в строке запроса
Элементов на странице, от 1 до 100 (по умолчанию 50). Подойдёт и limit.
curl "https://pik.li/api/v1/links?status=active&tag=promo&sort=clicks&per_page=20" \
-H "Authorization: Bearer $PIKLI_KEY"{
"links": [{
"id": 4821,
"short_url": "https://lnkz.li/spring-sale",
"slug": "spring-sale",
"domain": "lnkz.li",
"target_url": "https://example.com/shop/spring-sale",
"target_host": "example.com",
"title": "Spring sale",
"description": null,
"tags": ["promo", "newsletter"],
"status": "active",
"moderation": "allowed",
"active": true,
"expired": false,
"password_protected": false,
"clicks": 1284,
"unique_clicks": 902,
"last_clicked_at": "2026-09-23T09:58:12.431+02:00",
"expires_at": null,
"max_clicks": null,
"disabled_reason": null,
"utm": { "source": "newsletter", "medium": "email", "campaign": "spring" },
"preview_url": "https://lnkz.li/spring-sale+",
"qr_url": "https://pik.li/api/v1/links/4821/qr",
"created_at": "2026-09-01T08:30:05.117+02:00",
"updated_at": "2026-09-01T08:30:05.117+02:00"
}],
"pagination": { "page": 1, "per_page": 20, "total": 37, "total_pages": 2, "next_page": 2, "prev_page": null },
"page": 1,
"per_page": 20,
"total": 37
}/links/count
Счётчики панели управления одним вызовом: всего, активные, на рассмотрении, отключённые, отключённые модерацией, истёкшие, защищённые паролем, созданные сегодня, с кликами за последние 24 часа и истекающие в ближайшие 7 дней.
curl https://pik.li/api/v1/links/count \
-H "Authorization: Bearer $PIKLI_KEY"{
"total": 3187,
"active": 2954,
"review": 3,
"disabled": 41,
"moderated": 2,
"expired": 189,
"protected": 12,
"created_today": 9,
"active_24h": 214,
"expiring_7d": 6
}/links/active
Ссылки, по которым кликали люди за последние часы, — сначала те, у которых кликов больше всего; у каждой есть clicks_in_window и uniques_in_window.
hours
integer
в строке запроса
За сколько последних часов смотреть, от 1 до 168 (по умолчанию 24).
page
integer
в строке запроса
Номер страницы, начиная с 1.
per_page
integer
в строке запроса
Элементов на странице, от 1 до 100 (по умолчанию 50). Подойдёт и limit.
curl "https://pik.li/api/v1/links/active?hours=24" \
-H "Authorization: Bearer $PIKLI_KEY"{
"hours": 24,
"since": "2026-09-22T08:15:42Z",
"total_clicks": 3308,
"links": [{
"id": 4821,
"short_url": "https://lnkz.li/spring-sale",
"slug": "spring-sale",
"domain": "lnkz.li",
"target_url": "https://example.com/shop/spring-sale",
"target_host": "example.com",
"title": "Spring sale",
"description": null,
"tags": ["promo", "newsletter"],
"status": "active",
"moderation": "allowed",
"active": true,
"expired": false,
"password_protected": false,
"clicks": 1284,
"unique_clicks": 902,
"last_clicked_at": "2026-09-23T09:58:12.431+02:00",
"expires_at": null,
"max_clicks": null,
"disabled_reason": null,
"utm": { "source": "newsletter", "medium": "email", "campaign": "spring" },
"preview_url": "https://lnkz.li/spring-sale+",
"qr_url": "https://pik.li/api/v1/links/4821/qr",
"created_at": "2026-09-01T08:30:05.117+02:00",
"updated_at": "2026-09-01T08:30:05.117+02:00",
"clicks_in_window": 311,
"uniques_in_window": 240
}],
"pagination": { "page": 1, "per_page": 50, "total": 214, "total_pages": 5, "next_page": 2, "prev_page": null }
}/links/lookup
Передайте полный короткий адрес в url или отдельно domain и slug. Находятся только ваши собственные ссылки.
url
string
в строке запроса
Полный короткий адрес, например https://lnkz.li/spring-sale.
domain
string
в строке запроса
Вместо url: домен короткой ссылки…
slug
string
в строке запроса
…и её slug.
curl "https://pik.li/api/v1/links/lookup?url=https://lnkz.li/spring-sale" \
-H "Authorization: Bearer $PIKLI_KEY"{
"id": 4821,
"short_url": "https://lnkz.li/spring-sale",
"slug": "spring-sale",
"domain": "lnkz.li",
"target_url": "https://example.com/shop/spring-sale",
"target_host": "example.com",
"title": "Spring sale",
"description": null,
"tags": ["promo", "newsletter"],
"status": "active",
"moderation": "allowed",
"active": true,
"expired": false,
"password_protected": false,
"clicks": 1284,
"unique_clicks": 902,
"last_clicked_at": "2026-09-23T09:58:12.431+02:00",
"expires_at": null,
"max_clicks": null,
"disabled_reason": null,
"utm": { "source": "newsletter", "medium": "email", "campaign": "spring" },
"preview_url": "https://lnkz.li/spring-sale+",
"qr_url": "https://pik.li/api/v1/links/4821/qr",
"created_at": "2026-09-01T08:30:05.117+02:00",
"updated_at": "2026-09-01T08:30:05.117+02:00"
}/links/:id
Объект ссылки с актуальными счётчиками.
id
integer
в пути
обязательный
id ссылки.
curl https://pik.li/api/v1/links/4821 \
-H "Authorization: Bearer $PIKLI_KEY"{
"id": 4821,
"short_url": "https://lnkz.li/spring-sale",
"slug": "spring-sale",
"domain": "lnkz.li",
"target_url": "https://example.com/shop/spring-sale",
"target_host": "example.com",
"title": "Spring sale",
"description": null,
"tags": ["promo", "newsletter"],
"status": "active",
"moderation": "allowed",
"active": true,
"expired": false,
"password_protected": false,
"clicks": 1284,
"unique_clicks": 902,
"last_clicked_at": "2026-09-23T09:58:12.431+02:00",
"expires_at": null,
"max_clicks": null,
"disabled_reason": null,
"utm": { "source": "newsletter", "medium": "email", "campaign": "spring" },
"preview_url": "https://lnkz.li/spring-sale+",
"qr_url": "https://pik.li/api/v1/links/4821/qr",
"created_at": "2026-09-01T08:30:05.117+02:00",
"updated_at": "2026-09-01T08:30:05.117+02:00"
}/links
Idempotency-Key
Обязателен только url: pik.li сам выберет домен по умолчанию и случайный slug. Ссылка работает сразу, а автоматическая проверка проходит в течение нескольких минут (сначала moderation равен pending). Каждая ссылка учитывается в квоте вашего плана.
url
string
в теле JSON
обязательный
Адрес назначения. Если https:// не указан, он добавляется автоматически; хост должен быть настоящим доменным именем или IP-адресом. target_url принимается как синоним.
title
string
в теле JSON
Заголовок для вас, до 160 символов.
description
string
в теле JSON
Произвольные заметки.
tags
array | string
в теле JSON
Массив (["promo","autumn"]) или текст через запятую. Сохраняются в нижнем регистре, не более 10.
domain
string
в теле JSON
Имя хоста одного из ваших доменов (GET /domains). Если не указано, используется ваш домен по умолчанию.
slug
string
в теле JSON
Планы: Premium · Business
Собственное окончание короткого адреса: от 2 до 64 символов из строчных латинских букв, цифр, - и _. Если не указано, pik.li придумает его сам.
password
string
в теле JSON
Планы: Premium · Business
Посетители должны ввести его перед перенаправлением: от 4 до 72 символов.
expires_at
string
в теле JSON
Планы: Premium · Business
Когда ссылка перестанет работать (ISO 8601).
max_clicks
integer
в теле JSON
Планы: Premium · Business
После скольких кликов ссылка перестанет работать.
utm_source, utm_medium, utm_campaign, utm_term, utm_content
string
в теле JSON
Планы: Premium · Business
UTM-параметры, которые добавляются к адресу назначения при перенаправлении посетителя.
Idempotency-Key
string
в заголовке
Позволяет безопасно повторять вызов: см. «Идемпотентность».
curl -X POST https://pik.li/api/v1/links \
-H "Authorization: Bearer $PIKLI_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-spring" \
-d '{"url":"https://example.com/shop/spring-sale","title":"Spring sale","slug":"spring-sale","tags":["promo","newsletter"],"utm_source":"newsletter","utm_medium":"email","utm_campaign":"spring"}'{
"id": 4821,
"short_url": "https://lnkz.li/spring-sale",
"slug": "spring-sale",
"domain": "lnkz.li",
"target_url": "https://example.com/shop/spring-sale",
"target_host": "example.com",
"title": "Spring sale",
"description": null,
"tags": ["promo", "newsletter"],
"status": "active",
"moderation": "pending",
"active": true,
"expired": false,
"password_protected": false,
"clicks": 0,
"unique_clicks": 0,
"last_clicked_at": null,
"expires_at": null,
"max_clicks": null,
"disabled_reason": null,
"utm": { "source": "newsletter", "medium": "email", "campaign": "spring" },
"preview_url": "https://lnkz.li/spring-sale+",
"qr_url": "https://pik.li/api/v1/links/4821/qr",
"created_at": "2026-09-23T10:15:42.118+02:00",
"updated_at": "2026-09-23T10:15:42.118+02:00"
}/links/bulk
Idempotency-Key
Массив links, элементы которого содержат те же поля, что и POST /links. Вызов не работает по принципу «всё или ничего»: ответ перечисляет созданные ссылки, а для каждого элемента с ошибкой — его позицию (index) и ошибку. Статус ответа — 200, даже если часть элементов не удалась. У всех ссылок одного вызова общий batch_id.
links
array
в теле JSON
обязательный
Создаваемые ссылки, каждая с полями POST /links. Не более 10 за вызов, 100 — в планах с массовым созданием ссылок.
Idempotency-Key
string
в заголовке
Позволяет безопасно повторять вызов: см. «Идемпотентность».
curl -X POST https://pik.li/api/v1/links/bulk \
-H "Authorization: Bearer $PIKLI_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: import-2026-09-23-001" \
-d '{"links":[{"url":"https://example.com/a","tags":"autumn,promo"},{"url":"nope"}]}'{
"created": [{
"id": 4821,
"short_url": "https://lnkz.li/spring-sale",
"slug": "spring-sale",
"domain": "lnkz.li",
"target_url": "https://example.com/shop/spring-sale",
"target_host": "example.com",
"title": "Spring sale",
"description": null,
"tags": ["promo", "newsletter"],
"status": "active",
"moderation": "allowed",
"active": true,
"expired": false,
"password_protected": false,
"clicks": 1284,
"unique_clicks": 902,
"last_clicked_at": "2026-09-23T09:58:12.431+02:00",
"expires_at": null,
"max_clicks": null,
"disabled_reason": null,
"utm": { "source": "newsletter", "medium": "email", "campaign": "spring" },
"preview_url": "https://lnkz.li/spring-sale+",
"qr_url": "https://pik.li/api/v1/links/4821/qr",
"created_at": "2026-09-01T08:30:05.117+02:00",
"updated_at": "2026-09-01T08:30:05.117+02:00"
}],
"errors": [
{
"index": 1,
"url": "nope",
"error": {
"code": "invalid",
"message": "The request contains invalid data.",
"details": {
"fields": { "target_url": ["is not a web address: write it in full, for example example.com/page", "is invalid"] },
"messages": ["Destination URL is not a web address: write it in full, for example example.com/page", "Destination URL is invalid"]
},
"docs_url": "https://pik.li/help#error-invalid"
}
}
],
"batch_id": "api-tBUqFUYw",
"summary": { "requested": 2, "created": 1, "failed": 1, "quota_remaining": 2087, "max_items": 100 }
}/links/generate
Планы: Premium · Business
Idempotency-Key
Создаёт count коротких ссылок, у каждой свой случайный slug, и все они ведут на destination. В отличие от POST /links/bulk, вызов работает по принципу «всё или ничего»: если в вашем лимите осталось меньше ссылок, чем count, или адрес недопустим либо заблокирован, не создаётся ничего; при quota_exceeded поле details.remaining показывает, сколько ссылок ещё можно создать. Адрес проверяется один раз, и все ссылки начинают с одинаковым результатом модерации. У ссылок общий batch_id, начинающийся с gen-; та же партия видна в панели управления вместе с CSV.
destination
string
в теле JSON
обязательный
Адрес, на который ведут все ссылки. Если https:// не указан, он добавляется автоматически. Параметр url принимается как синоним.
count
integer
в теле JSON
обязательный
Сколько ссылок создать: от 2 до максимума на один вызов, который устанавливает pik.li. Если больше, ответ — invalid_parameter, а предел указан в details.max.
domain
string
в теле JSON
Имя хоста одного из ваших доменов (GET /domains). Если не указано, используется ваш домен по умолчанию.
title_prefix
string
в теле JSON
Необязательно. Каждая ссылка получает его в качестве заголовка вместе со своим номером: Столик 001, Столик 002…
tags
array | string
в теле JSON
Массив (["promo","autumn"]) или текст через запятую. Сохраняются в нижнем регистре, не более 10.
expires_at
string
в теле JSON
Планы: Premium · Business
Когда ссылка перестанет работать (ISO 8601).
Idempotency-Key
string
в заголовке
Позволяет безопасно повторять вызов: см. «Идемпотентность».
curl -X POST https://pik.li/api/v1/links/generate \
-H "Authorization: Bearer $PIKLI_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: menu-tables-2026-09" \
-d '{"destination":"https://example.com/menu","count":3,"title_prefix":"Table","tags":["menu"]}'{
"batch_id": "gen-7XkQ2mPa",
"destination": "https://example.com/menu",
"created": 3,
"quota_remaining": 2085,
"links": [{
"id": 5310,
"short_url": "https://lnkz.li/k7qm2xd",
"slug": "k7qm2xd",
"domain": "lnkz.li",
"target_url": "https://example.com/menu",
"target_host": "example.com",
"title": "Table 001",
"description": null,
"tags": ["menu"],
"status": "active",
"moderation": "allowed",
"active": true,
"expired": false,
"password_protected": false,
"clicks": 0,
"unique_clicks": 0,
"last_clicked_at": null,
"expires_at": null,
"max_clicks": null,
"disabled_reason": null,
"utm": null,
"preview_url": "https://lnkz.li/k7qm2xd+",
"qr_url": "https://pik.li/api/v1/links/5310/qr",
"created_at": "2026-09-24T11:02:18.402+02:00",
"updated_at": "2026-09-24T11:02:18.402+02:00"
}]
}/links/:id
Передавайте только те поля, которые хотите изменить. Домен изменить нельзя. Новый адрес назначения снова проходит автоматическую проверку.
Также принимается PUT с теми же параметрами.
id
integer
в пути
обязательный
id ссылки.
url
string
в теле JSON
Новый адрес назначения. Ссылка возвращается в состояние moderation: pending, пока не пройдёт проверку заново.
title
string
в теле JSON
Заголовок для вас, до 160 символов.
description
string
в теле JSON
Произвольные заметки.
tags
array | string
в теле JSON
Заменяет все теги ссылки. Пустой массив удаляет их.
slug
string
в теле JSON
Планы: Premium · Business
Собственное окончание короткого адреса: от 2 до 64 символов из строчных латинских букв, цифр, - и _. Если не указано, pik.li придумает его сам.
password
string
в теле JSON
Планы: Premium · Business
Посетители должны ввести его перед перенаправлением: от 4 до 72 символов.
expires_at
string | null
в теле JSON
Планы: Premium · Business
Новая дата истечения; null убирает её.
max_clicks
integer | null
в теле JSON
Планы: Premium · Business
Новый лимит кликов; null убирает его.
utm_source, utm_medium, utm_campaign, utm_term, utm_content
string
в теле JSON
Планы: Premium · Business
UTM-параметры, которые добавляются к адресу назначения при перенаправлении посетителя.
curl -X PATCH https://pik.li/api/v1/links/4821 \
-H "Authorization: Bearer $PIKLI_KEY" \
-H "Content-Type: application/json" \
-d '{"title":"Spring sale","tags":["promo","newsletter"]}'{
"id": 4821,
"short_url": "https://lnkz.li/spring-sale",
"slug": "spring-sale",
"domain": "lnkz.li",
"target_url": "https://example.com/shop/spring-sale",
"target_host": "example.com",
"title": "Spring sale",
"description": null,
"tags": ["promo", "newsletter"],
"status": "active",
"moderation": "allowed",
"active": true,
"expired": false,
"password_protected": false,
"clicks": 1284,
"unique_clicks": 902,
"last_clicked_at": "2026-09-23T09:58:12.431+02:00",
"expires_at": null,
"max_clicks": null,
"disabled_reason": null,
"utm": { "source": "newsletter", "medium": "email", "campaign": "spring" },
"preview_url": "https://lnkz.li/spring-sale+",
"qr_url": "https://pik.li/api/v1/links/4821/qr",
"created_at": "2026-09-01T08:30:05.117+02:00",
"updated_at": "2026-09-01T08:30:05.117+02:00"
}/links/:id
Короткий адрес перестаёт работать, а ссылка исчезает из списков и статистики. Через API это действие отменить нельзя.
id
integer
в пути
обязательный
id ссылки.
curl -X DELETE https://pik.li/api/v1/links/4821 \
-H "Authorization: Bearer $PIKLI_KEY"/links/:id/disable
Вместо перенаправления короткий адрес показывает уведомление, пока вы снова не включите ссылку. В ответе — обновлённая ссылка.
id
integer
в пути
обязательный
id ссылки.
curl -X POST https://pik.li/api/v1/links/4821/disable \
-H "Authorization: Bearer $PIKLI_KEY"{
"id": 4821,
"short_url": "https://lnkz.li/spring-sale",
"slug": "spring-sale",
"domain": "lnkz.li",
"target_url": "https://example.com/shop/spring-sale",
"target_host": "example.com",
"title": "Spring sale",
"description": null,
"tags": ["promo", "newsletter"],
"status": "disabled",
"moderation": "allowed",
"active": false,
"expired": false,
"password_protected": false,
"clicks": 1284,
"unique_clicks": 902,
"last_clicked_at": "2026-09-23T09:58:12.431+02:00",
"expires_at": null,
"max_clicks": null,
"disabled_reason": "Disabled by the owner",
"utm": { "source": "newsletter", "medium": "email", "campaign": "spring" },
"preview_url": "https://lnkz.li/spring-sale+",
"qr_url": "https://pik.li/api/v1/links/4821/qr",
"created_at": "2026-09-01T08:30:05.117+02:00",
"updated_at": "2026-09-23T10:15:42.118+02:00"
}/links/:id/enable
Работает для ссылок, которые вы приостановили сами. Для ссылки, отключённой модерацией, ответ — 409 link_blocked: в этом случае подайте апелляцию из панели управления.
id
integer
в пути
обязательный
id ссылки.
curl -X POST https://pik.li/api/v1/links/4821/enable \
-H "Authorization: Bearer $PIKLI_KEY"{
"id": 4821,
"short_url": "https://lnkz.li/spring-sale",
"slug": "spring-sale",
"domain": "lnkz.li",
"target_url": "https://example.com/shop/spring-sale",
"target_host": "example.com",
"title": "Spring sale",
"description": null,
"tags": ["promo", "newsletter"],
"status": "active",
"moderation": "allowed",
"active": true,
"expired": false,
"password_protected": false,
"clicks": 1284,
"unique_clicks": 902,
"last_clicked_at": "2026-09-23T09:58:12.431+02:00",
"expires_at": null,
"max_clicks": null,
"disabled_reason": null,
"utm": { "source": "newsletter", "medium": "email", "campaign": "spring" },
"preview_url": "https://lnkz.li/spring-sale+",
"qr_url": "https://pik.li/api/v1/links/4821/qr",
"created_at": "2026-09-01T08:30:05.117+02:00",
"updated_at": "2026-09-01T08:30:05.117+02:00"
}/links/:id/stats
Клики и уникальные посетители за окно в сравнении с предыдущим окном, временной ряд и разбивки по стране, устройству, браузеру, операционной системе, языку, источнику, часу суток и городу. Разбивки для одной ссылки — объекты ({"IT": 188}); series повторяет временной ряд в виде пар для старых клиентов.
id
integer
в пути
обязательный
id ссылки.
period
string
в строке запроса
Окно: 24h, 7d, 30d (по умолчанию), 90d, 1y, all. См. «Окна статистики».
from
string
в строке запроса
Начало окна вместо period: дата или время в формате ISO 8601.
to
string
в строке запроса
Конец окна (по умолчанию — текущий момент).
interval
string
в строке запроса
hour или day — шаг временного ряда.
curl "https://pik.li/api/v1/links/4821/stats?period=7d" \
-H "Authorization: Bearer $PIKLI_KEY"{
"id": 4821,
"short_url": "https://lnkz.li/spring-sale",
"clicks": 1284,
"unique": 902,
"period_days": 7,
"period_clicks": 311,
"window": {
"from": "2026-09-17T00:00:00+02:00",
"to": "2026-09-23T10:15:42+02:00",
"days": 7,
"interval": "day",
"period": "7d",
"clamped": false,
"retention_days": 730,
"previous": { "from": "2026-09-10T00:00:00+02:00", "to": "2026-09-17T00:00:00+02:00" }
},
"period": { "clicks": 311, "uniques": 240, "bots": 18 },
"previous": { "clicks": 265, "uniques": 201, "delta_pct": 17.4 },
"series": [["2026-09-17", 38], ["2026-09-18", 52]],
"timeseries": {
"interval": "day",
"points": [
{ "at": "2026-09-17", "clicks": 38, "uniques": 30 },
{ "at": "2026-09-18", "clicks": 52, "uniques": 41 }
]
},
"countries": { "IT": 188, "DE": 61, "FR": 34 },
"devices": { "mobile": 204, "desktop": 101, "tablet": 6 },
"browsers": { "Chrome": 142, "Safari": 120, "Firefox": 31 },
"os": { "iOS": 118, "Android": 86, "Windows": 64 },
"languages": { "it": 190, "de": 58, "en": 40 },
"referrers": { "instagram.com": 97, "google.com": 44 },
"cities": { "Milano": 61, "Roma": 38 },
"hourly": { "0": 3, "1": 1, "2": 0, "3": 0, "4": 0, "5": 1, "6": 4, "7": 9, "8": 17, "9": 21, "10": 19, "11": 18,
"12": 24, "13": 22, "14": 16, "15": 15, "16": 17, "17": 20, "18": 23, "19": 21, "20": 19, "21": 14, "22": 11, "23": 9 }
}/links/:id/clicks
Сначала самые новые, в пределах истории, которую хранит ваш план. ip — адрес посетителя со скрытой последней частью (151.78.52.•••, у IPv6 — первые три группы); полный адрес через API не передаётся. Поля без значения в клик не включаются.
id
integer
в пути
обязательный
id ссылки.
period
string
в строке запроса
Окно, по умолчанию all. См. «Окна статистики».
from
string
в строке запроса
Начало окна вместо period: дата или время в формате ISO 8601.
to
string
в строке запроса
Конец окна (по умолчанию — текущий момент).
bots
string
в строке запроса
1, чтобы учитывать и клики ботов.
page
integer
в строке запроса
Номер страницы, начиная с 1.
per_page
integer
в строке запроса
Элементов на странице, от 1 до 100 (по умолчанию 50). Подойдёт и limit.
curl "https://pik.li/api/v1/links/4821/clicks?period=24h&per_page=2" \
-H "Authorization: Bearer $PIKLI_KEY"{
"window": {
"from": "2026-09-22T10:15:42+02:00",
"to": "2026-09-23T10:15:42+02:00",
"days": 1,
"interval": "hour",
"period": "24h",
"clamped": false,
"retention_days": 730,
"previous": { "from": "2026-09-21T10:15:42+02:00", "to": "2026-09-22T10:15:42+02:00" }
},
"clicks": [
{
"id": 918273,
"occurred_at": "2026-09-23T09:58:12.431+02:00",
"ip": "151.78.52.•••",
"country": "IT",
"region": "Lombardy",
"city": "Milano",
"device": "mobile",
"browser": "Safari",
"os": "iOS",
"language": "it",
"referrer_host": "instagram.com",
"referrer": "https://instagram.com/",
"bot": false,
"unique": true
}
],
"pagination": { "page": 1, "per_page": 2, "total": 44, "total_pages": 22, "next_page": 2, "prev_page": null }
}/links/:id/qr.{svg|png}
QR-код короткого адреса с теми же цветами и логотипом, которые вы выбрали в панели управления. Формат — .svg, если не запросить .png.
id
integer
в пути
обязательный
id ссылки.
format
string
в пути
Расширение: .svg (по умолчанию) или .png.
size
integer
в строке запроса
Сторона в пикселях: 128–2048 для PNG (по умолчанию 512), 64–1024 для SVG (по умолчанию 240).
curl "https://pik.li/api/v1/links/4821/qr.png?size=1024" \
-H "Authorization: Bearer $PIKLI_KEY" \
-o spring-sale-qr.pngimage/svg+xml, image/png.Показатели всех ваших ссылок вместе, с теми же фильтрами, что и в панели управления: окно, домен, тег, боты. Общие параметры описаны в разделе «Окна статистики».
/stats
Итоги по аккаунту, окно в сравнении с предыдущим, временной ряд, первые 10 источников и стран, первые 6 устройств, браузеров и операционных систем и 10 ссылок с наибольшим числом кликов. Остальные эндпоинты /stats возвращают каждую часть отдельно и с более длинными списками.
period
string
в строке запроса
Окно: 24h, 7d (по умолчанию), 30d, 90d, 1y, all. См. «Окна статистики».
from
string
в строке запроса
Начало окна вместо period: дата или время в формате ISO 8601.
to
string
в строке запроса
Конец окна (по умолчанию — текущий момент).
interval
string
в строке запроса
hour или day — шаг временного ряда.
domain
string
в строке запроса
Только этот домен, по имени хоста (например, lnkz.li). Домен должен быть одним из ваших: см. GET /domains.
tag
string
в строке запроса
Только ссылки с этим тегом.
bots
string
в строке запроса
1, чтобы учитывать и клики ботов.
curl "https://pik.li/api/v1/stats?period=7d" \
-H "Authorization: Bearer $PIKLI_KEY"{
"window": {
"from": "2026-09-17T00:00:00+02:00",
"to": "2026-09-23T10:15:42+02:00",
"days": 7,
"interval": "day",
"period": "7d",
"clamped": false,
"retention_days": 730,
"previous": { "from": "2026-09-10T00:00:00+02:00", "to": "2026-09-17T00:00:00+02:00" }
},
"filters": { "bots": false },
"totals": {
"links": 3187, "active_links": 2954, "clicks": 402118, "unique_clicks": 288930,
"clicks_today": 1204, "links_active_24h": 214, "links_created_in_window": 61
},
"period": { "clicks": 21480, "uniques": 15522, "links_clicked": 690, "clicks_per_link": 31.1 },
"previous": { "clicks": 19870, "uniques": 14410, "links_clicked": 655, "clicks_per_link": 30.3, "delta_pct": 8.1, "uniques_delta_pct": 7.7 },
"timeseries": {
"interval": "day",
"points": [
{ "at": "2026-09-17", "clicks": 2890, "uniques": 2104 },
{ "at": "2026-09-18", "clicks": 3120, "uniques": 2240 }
]
},
"referrers": [{ "referrer": "instagram.com", "clicks": 5210, "share": 24.3 }],
"direct": 8740,
"countries": [{ "country": "IT", "clicks": 12877, "share": 59.9 }],
"devices": [{ "device": "mobile", "clicks": 14002, "share": 65.2 }],
"browsers": [{ "browser": "Chrome", "clicks": 9406, "share": 43.8 }],
"os": [{ "os": "iOS", "clicks": 7340, "share": 34.2 }],
"top_links": [{
"id": 4821,
"short_url": "https://lnkz.li/spring-sale",
"slug": "spring-sale",
"domain": "lnkz.li",
"target_url": "https://example.com/shop/spring-sale",
"target_host": "example.com",
"title": "Spring sale",
"description": null,
"tags": ["promo", "newsletter"],
"status": "active",
"moderation": "allowed",
"active": true,
"expired": false,
"password_protected": false,
"clicks": 1284,
"unique_clicks": 902,
"last_clicked_at": "2026-09-23T09:58:12.431+02:00",
"expires_at": null,
"max_clicks": null,
"disabled_reason": null,
"utm": { "source": "newsletter", "medium": "email", "campaign": "spring" },
"preview_url": "https://lnkz.li/spring-sale+",
"qr_url": "https://pik.li/api/v1/links/4821/qr",
"created_at": "2026-09-01T08:30:05.117+02:00",
"updated_at": "2026-09-01T08:30:05.117+02:00",
"clicks_in_window": 311,
"uniques_in_window": 240
}]
}/stats/timeseries
Клики и уникальные посетители по часам или по дням, с итогом предыдущего окна и изменением в процентах.
period
string
в строке запроса
Окно: 24h, 7d (по умолчанию), 30d, 90d, 1y, all. См. «Окна статистики».
from
string
в строке запроса
Начало окна вместо period: дата или время в формате ISO 8601.
to
string
в строке запроса
Конец окна (по умолчанию — текущий момент).
interval
string
в строке запроса
hour или day — шаг временного ряда.
domain
string
в строке запроса
Только этот домен, по имени хоста (например, lnkz.li). Домен должен быть одним из ваших: см. GET /domains.
tag
string
в строке запроса
Только ссылки с этим тегом.
bots
string
в строке запроса
1, чтобы учитывать и клики ботов.
curl "https://pik.li/api/v1/stats/timeseries?period=24h" \
-H "Authorization: Bearer $PIKLI_KEY"{
"window": {
"from": "2026-09-22T10:15:42+02:00",
"to": "2026-09-23T10:15:42+02:00",
"days": 1,
"interval": "hour",
"period": "24h",
"clamped": false,
"retention_days": 730,
"previous": { "from": "2026-09-21T10:15:42+02:00", "to": "2026-09-22T10:15:42+02:00" }
},
"filters": { "bots": false },
"interval": "hour",
"clicks": 3308,
"previous_clicks": 2977,
"delta_pct": 11.1,
"points": [
{ "at": "2026-09-22T08:00:00Z", "clicks": 131, "uniques": 97 },
{ "at": "2026-09-22T09:00:00Z", "clicks": 158, "uniques": 120 }
]
}/stats/referrers
Сайты, которые привели больше всего кликов, с долей каждого от общего числа, а также клики без источника (direct).
period
string
в строке запроса
Окно: 24h, 7d (по умолчанию), 30d, 90d, 1y, all. См. «Окна статистики».
from
string
в строке запроса
Начало окна вместо period: дата или время в формате ISO 8601.
to
string
в строке запроса
Конец окна (по умолчанию — текущий момент).
domain
string
в строке запроса
Только этот домен, по имени хоста (например, lnkz.li). Домен должен быть одним из ваших: см. GET /domains.
tag
string
в строке запроса
Только ссылки с этим тегом.
bots
string
в строке запроса
1, чтобы учитывать и клики ботов.
limit
integer
в строке запроса
Сколько строк в каждом списке, от 1 до 50 (по умолчанию 10).
curl "https://pik.li/api/v1/stats/referrers?period=30d&limit=5" \
-H "Authorization: Bearer $PIKLI_KEY"{
"window": {
"from": "2026-09-17T00:00:00+02:00",
"to": "2026-09-23T10:15:42+02:00",
"days": 7,
"interval": "day",
"period": "7d",
"clamped": false,
"retention_days": 730,
"previous": { "from": "2026-09-10T00:00:00+02:00", "to": "2026-09-17T00:00:00+02:00" }
},
"filters": { "bots": false },
"clicks": 21480,
"direct": 8740,
"referrers": [
{ "referrer": "instagram.com", "clicks": 5210, "share": 24.3 },
{ "referrer": "google.com", "clicks": 3011, "share": 14.0 }
]
}/stats/countries
Страны в виде ISO-кодов с их долей; cities доступен в планах с полной статистикой.
period
string
в строке запроса
Окно: 24h, 7d (по умолчанию), 30d, 90d, 1y, all. См. «Окна статистики».
from
string
в строке запроса
Начало окна вместо period: дата или время в формате ISO 8601.
to
string
в строке запроса
Конец окна (по умолчанию — текущий момент).
domain
string
в строке запроса
Только этот домен, по имени хоста (например, lnkz.li). Домен должен быть одним из ваших: см. GET /domains.
tag
string
в строке запроса
Только ссылки с этим тегом.
bots
string
в строке запроса
1, чтобы учитывать и клики ботов.
limit
integer
в строке запроса
Сколько строк в каждом списке, от 1 до 50 (по умолчанию 10).
curl "https://pik.li/api/v1/stats/countries?period=30d" \
-H "Authorization: Bearer $PIKLI_KEY"{
"window": {
"from": "2026-09-17T00:00:00+02:00",
"to": "2026-09-23T10:15:42+02:00",
"days": 7,
"interval": "day",
"period": "7d",
"clamped": false,
"retention_days": 730,
"previous": { "from": "2026-09-10T00:00:00+02:00", "to": "2026-09-17T00:00:00+02:00" }
},
"filters": { "bots": false },
"clicks": 21480,
"countries": [
{ "country": "IT", "clicks": 12877, "share": 59.9 },
{ "country": "DE", "clicks": 2630, "share": 12.2 }
],
"cities": [
{ "city": "Milano", "clicks": 3120, "share": 14.5 },
{ "city": "Roma", "clicks": 2210, "share": 10.3 }
]
}/stats/devices
Четыре списка одним вызовом, в каждом — клики и доля от общего числа.
period
string
в строке запроса
Окно: 24h, 7d (по умолчанию), 30d, 90d, 1y, all. См. «Окна статистики».
from
string
в строке запроса
Начало окна вместо period: дата или время в формате ISO 8601.
to
string
в строке запроса
Конец окна (по умолчанию — текущий момент).
domain
string
в строке запроса
Только этот домен, по имени хоста (например, lnkz.li). Домен должен быть одним из ваших: см. GET /domains.
tag
string
в строке запроса
Только ссылки с этим тегом.
bots
string
в строке запроса
1, чтобы учитывать и клики ботов.
limit
integer
в строке запроса
Сколько строк в каждом списке, от 1 до 50 (по умолчанию 10).
curl "https://pik.li/api/v1/stats/devices?period=30d" \
-H "Authorization: Bearer $PIKLI_KEY"{
"window": {
"from": "2026-09-17T00:00:00+02:00",
"to": "2026-09-23T10:15:42+02:00",
"days": 7,
"interval": "day",
"period": "7d",
"clamped": false,
"retention_days": 730,
"previous": { "from": "2026-09-10T00:00:00+02:00", "to": "2026-09-17T00:00:00+02:00" }
},
"filters": { "bots": false },
"clicks": 21480,
"devices": [{ "device": "mobile", "clicks": 14002, "share": 65.2 }, { "device": "desktop", "clicks": 7100, "share": 33.1 }],
"browsers": [{ "browser": "Chrome", "clicks": 9406, "share": 43.8 }],
"os": [{ "os": "iOS", "clicks": 7340, "share": 34.2 }],
"languages": [{ "language": "it", "clicks": 12690, "share": 59.1 }]
}/stats/top
Ссылки с наибольшим числом кликов за окно, у каждой есть clicks_in_window и uniques_in_window.
period
string
в строке запроса
Окно: 24h, 7d (по умолчанию), 30d, 90d, 1y, all. См. «Окна статистики».
from
string
в строке запроса
Начало окна вместо period: дата или время в формате ISO 8601.
to
string
в строке запроса
Конец окна (по умолчанию — текущий момент).
domain
string
в строке запроса
Только этот домен, по имени хоста (например, lnkz.li). Домен должен быть одним из ваших: см. GET /domains.
tag
string
в строке запроса
Только ссылки с этим тегом.
bots
string
в строке запроса
1, чтобы учитывать и клики ботов.
limit
integer
в строке запроса
Сколько строк в каждом списке, от 1 до 50 (по умолчанию 10).
curl "https://pik.li/api/v1/stats/top?period=7d&limit=10" \
-H "Authorization: Bearer $PIKLI_KEY"{
"window": {
"from": "2026-09-17T00:00:00+02:00",
"to": "2026-09-23T10:15:42+02:00",
"days": 7,
"interval": "day",
"period": "7d",
"clamped": false,
"retention_days": 730,
"previous": { "from": "2026-09-10T00:00:00+02:00", "to": "2026-09-17T00:00:00+02:00" }
},
"filters": { "bots": false },
"clicks": 21480,
"links": [{
"id": 4821,
"short_url": "https://lnkz.li/spring-sale",
"slug": "spring-sale",
"domain": "lnkz.li",
"target_url": "https://example.com/shop/spring-sale",
"target_host": "example.com",
"title": "Spring sale",
"description": null,
"tags": ["promo", "newsletter"],
"status": "active",
"moderation": "allowed",
"active": true,
"expired": false,
"password_protected": false,
"clicks": 1284,
"unique_clicks": 902,
"last_clicked_at": "2026-09-23T09:58:12.431+02:00",
"expires_at": null,
"max_clicks": null,
"disabled_reason": null,
"utm": { "source": "newsletter", "medium": "email", "campaign": "spring" },
"preview_url": "https://lnkz.li/spring-sale+",
"qr_url": "https://pik.li/api/v1/links/4821/qr",
"created_at": "2026-09-01T08:30:05.117+02:00",
"updated_at": "2026-09-01T08:30:05.117+02:00",
"clicks_in_window": 311,
"uniques_in_window": 240
}]
}Домены, на которых могут работать ваши короткие ссылки.
/domains
Домены pik.li, разрешённые вашим планом, и ваши подтверждённые собственные домены; какой из них используется по умолчанию и сколько собственных доменов допускает ваш план. При создании ссылки передавайте hostname в поле domain.
curl https://pik.li/api/v1/domains \
-H "Authorization: Bearer $PIKLI_KEY"{
"domains": [
{ "id": 1, "hostname": "lnkz.li", "base_url": "https://lnkz.li", "kind": "system", "min_plan": "free", "status": "active", "verified": true, "default": true },
{ "id": 318, "hostname": "go.example.com", "base_url": "https://go.example.com", "kind": "custom", "min_plan": "free", "status": "active", "verified": true, "default": false }
],
"default": "lnkz.li",
"custom_domains": { "used": 1, "limit": 3 }
}Управляйте из своего кода вебхуками, которые иначе настраивались бы на странице «Вебхуки» панели управления. Как работают доставки, описано ниже в разделе «Вебхуки».
/webhooks
Ваши вебхуки и события, на которые можно подписаться. После создания секрет больше никогда не показывается.
curl https://pik.li/api/v1/webhooks \
-H "Authorization: Bearer $PIKLI_KEY"{
"webhooks": [{
"id": 17,
"url": "https://example.com/hooks/pikli",
"events": ["link.created", "link.disabled"],
"active": true,
"failures_count": 0,
"last_delivered_at": "2026-09-22T18:04:11.520+02:00",
"created_at": "2026-09-10T11:20:33.004+02:00",
"updated_at": "2026-09-10T11:20:33.004+02:00",
"signature_header": "X-Pikli-Signature"
}],
"events": ["link.created", "link.clicked", "link.disabled", "link.deleted"]
}/webhooks/:id
Вебхук с последними 20 доставками и статусом, которым ваш сервер ответил на каждую из них.
id
integer
в пути
обязательный
id вебхука.
curl https://pik.li/api/v1/webhooks/17 \
-H "Authorization: Bearer $PIKLI_KEY"{
"id": 17,
"url": "https://example.com/hooks/pikli",
"events": ["link.created", "link.disabled"],
"active": true,
"failures_count": 0,
"last_delivered_at": "2026-09-22T18:04:11.520+02:00",
"created_at": "2026-09-10T11:20:33.004+02:00",
"updated_at": "2026-09-10T11:20:33.004+02:00",
"signature_header": "X-Pikli-Signature",
"deliveries": [
{ "id": 903, "event": "ping", "response_code": 200, "attempts": 1, "delivered_at": "2026-09-22T18:04:11.520+02:00", "created_at": "2026-09-22T18:04:11.520+02:00" }
]
}/webhooks
Ответ содержит secret, которым подписываются доставки, — только в этот раз: сохраните его сразу.
url
string
в теле JSON
обязательный
Адрес, на который приходят доставки: http:// или https://, доступный из интернета.
events
array | string
в теле JSON
События, которые нужно получать, массивом или через запятую. Если не указано — все. Список событий см. ниже.
active
boolean
в теле JSON
false, чтобы создать вебхук приостановленным. По умолчанию true.
curl -X POST https://pik.li/api/v1/webhooks \
-H "Authorization: Bearer $PIKLI_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/hooks/pikli","events":["link.created","link.disabled"]}'{
"id": 17,
"url": "https://example.com/hooks/pikli",
"events": ["link.created", "link.disabled"],
"active": true,
"failures_count": 0,
"last_delivered_at": null,
"created_at": "2026-09-10T11:20:33.004+02:00",
"updated_at": "2026-09-10T11:20:33.004+02:00",
"signature_header": "X-Pikli-Signature",
"secret": "ec307f56cfac71856a10d641eee7dd58e0eb8286"
}/webhooks/:id
Передавайте только то, что меняется: адрес, события или active, чтобы приостановить или возобновить доставки.
Также принимается PUT с теми же параметрами.
id
integer
в пути
обязательный
id вебхука.
url
string
в теле JSON
Новый адрес.
events
array | string
в теле JSON
Новый список событий; он не может быть пустым.
active
boolean
в теле JSON
false приостанавливает доставки, true возобновляет их.
curl -X PATCH https://pik.li/api/v1/webhooks/17 \
-H "Authorization: Bearer $PIKLI_KEY" \
-H "Content-Type: application/json" \
-d '{"active":false}'{
"id": 17,
"url": "https://example.com/hooks/pikli",
"events": ["link.created", "link.disabled"],
"active": false,
"failures_count": 0,
"last_delivered_at": "2026-09-22T18:04:11.520+02:00",
"created_at": "2026-09-10T11:20:33.004+02:00",
"updated_at": "2026-09-23T10:15:42.118+02:00",
"signature_header": "X-Pikli-Signature"
}/webhooks/:id
Доставки прекращаются, а их история удаляется вместе с вебхуком.
id
integer
в пути
обязательный
id вебхука.
curl -X DELETE https://pik.li/api/v1/webhooks/17 \
-H "Authorization: Bearer $PIKLI_KEY"/webhooks/:id/test
Ставит в очередь ping на адрес вебхука, подписанный так же, как любая доставка: самый быстрый способ проверить ваш код проверки подписи. Доставка уходит вскоре после вызова и появляется в GET /webhooks/:id.
id
integer
в пути
обязательный
id вебхука.
curl -X POST https://pik.li/api/v1/webhooks/17/test \
-H "Authorization: Bearer $PIKLI_KEY"{
"queued": true,
"event": "ping",
"webhook_id": 17
}Вебхук — это адрес на вашем сервере, на который pik.li отправляет POST-запрос, когда в вашем аккаунте что-то происходит. Создать его можно на странице «Вебхуки» панели управления или через эндпоинты вебхуков.
pinglink.createdlink.clickedlink.disabledlink.deletedЭто POST-запрос с JSON-телом из трёх полей: event — название события, created_at — время отправки, data — подробности события. Вместе с ним приходят такие заголовки:
POST /hooks/pikli HTTP/1.1
Content-Type: application/json
X-Pikli-Event: ping
X-Pikli-Signature: sha256=bdaf35d42413498dab7fea8be1f292c36b690152e5ec7d66e6dd2c2cd0b2d61c
{"event":"ping","created_at":"2026-09-23T10:15:42+02:00","data":{"message":"pik.li webhook test","at":"2026-09-23T10:15:42+02:00","via":"api"}}Content-TypeX-Pikli-EventX-Pikli-SignatureКаждая доставка подписывается секретом своего вебхука, который вы получаете один раз — при его создании. Заголовок X-Pikli-Signature содержит sha256=, за которым следует HMAC-SHA256 исходного тела в шестнадцатеричном виде. Вычислите такой же HMAC по полученным байтам — до разбора JSON, который бы их изменил, — и сравните две строки за постоянное время. Если они различаются, ответьте 401 и проигнорируйте запрос.
Чтобы проверить свой код: с секретом ec307f56cfac71856a10d641eee7dd58e0eb8286 из примера выше тело показанной здесь доставки даёт в точности подпись из её заголовка.
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post("/hooks/pikli", express.raw({ type: "application/json" }), (req, res) => {
const expected = "sha256=" + crypto
.createHmac("sha256", process.env.PIKLI_WEBHOOK_SECRET)
.update(req.body)
.digest("hex");
const received = req.get("X-Pikli-Signature") || "";
const valid = received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
if (!valid) return res.sendStatus(401);
const event = JSON.parse(req.body);
res.sendStatus(204);
});import hashlib, hmac, os
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["PIKLI_WEBHOOK_SECRET"].encode()
@app.post("/hooks/pikli")
def pikli_hook():
body = request.get_data()
expected = "sha256=" + hmac.new(SECRET, body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-Pikli-Signature", "")):
abort(401)
event = request.get_json()
return "", 204class PikliHooksController < ActionController::API
def create
body = request.raw_post
expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", ENV.fetch("PIKLI_WEBHOOK_SECRET"), body)
received = request.headers["X-Pikli-Signature"].to_s
return head(:unauthorized) unless ActiveSupport::SecurityUtils.secure_compare(expected, received)
event = JSON.parse(body)
head :no_content
end
end<?php
$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, getenv('PIKLI_WEBHOOK_SECRET'));
$received = $_SERVER['HTTP_X_PIKLI_SIGNATURE'] ?? '';
if (!hash_equals($expected, $received)) {
http_response_code(401);
exit;
}
$event = json_decode($body, true);
http_response_code(204);2xx как можно скорее, а медленную работу выполняйте уже после ответа.400 и выше записывается и не повторяется. Он увеличивает на единицу failures_count вебхука; счётчик обнуляется при первой же успешной доставке.GET /webhooks/:id и на странице «Вебхуки» панели управления.https://, чтобы доставки передавались в зашифрованном виде.Та же справка в машиночитаемом виде опубликована по адресу /openapi.json (OpenAPI 3.1). Импортируйте её в Postman, Insomnia или Bruno либо сгенерируйте клиент с помощью openapi-generator.
Чего-то не хватает или что-то работает не так, как написано на этой странице? Напишите на [email protected].