KLO Public APIKLO Public API

ОбзорOverview

Чтение: список кампаний и их настройки, счётчики трафика (белая страница / оффер), графики по дням и часам, история кликов, живая лента решений, домены. Запись: создание, изменение, включение/отключение и удаление кампаний, а также готовый файл интеграции. Всё в пределах вашей подписки и тарифа - от лица вашего аккаунта, без входа в кабинет. Read: list campaigns and their settings, traffic counters (white page / offer), day/hour charts, click history, a live decision feed, and domains. Write: create, update, enable/disable and delete campaigns, plus the ready-to-deploy integration file. Everything within your subscription and plan - on behalf of your account, without logging into the cabinet.

Первый запрос за три шагаYour first request in three steps

1. В кабинете, раздел «API», создайте токен с правом чтения. Для управления кампаниями дополнительно включите запись.Create a read token in Cabinet → API. Enable write access only if your tool needs to manage campaigns.
2. На своём сервере сохраните токен в переменную окружения KLO_API_TOKEN и выполните пример ниже. Во всех остальных примерах заменяйте klo_live_… на свой токен.On your server, store the token in the KLO_API_TOKEN environment variable and run the example below. Replace klo_live_… in other examples with your own token.
3. Проверьте HTTP 200, свой тариф и data.limits. Далее запросите /campaigns или /stats. Примеры cURL рассчитаны на Bash; в PowerShell используйте curl.exe и синтаксис своей оболочки.Check for HTTP 200, your plan and data.limits. Then request /campaigns or /stats. cURL examples use Bash syntax; in PowerShell use curl.exe and your shell's quoting syntax.

curl --silent --show-error --fail-with-body --max-time 30 \
  -H "Authorization: Bearer $KLO_API_TOKEN" \
  https://cabinet.klo-boostclicks.online/api/v1/account

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

API использует отдельные Bearer-токены вида klo_live_…. Это не тот же секрет, что вшит в лоадер, - токены выпускаются и отзываются отдельно, специально для API. The API uses dedicated Bearer tokens shaped like klo_live_…. These are not the loader secret - API tokens are issued and revoked separately, exclusively for the API.

Как получить токенGetting a token

• Откройте кабинет → вкладка «API».Open the cabinet → the “API” tab.
• Нажмите «Создать токен», задайте название.Click “Create token” and give it a name.
• Скопируйте токен в настройки своего приложения. Новые токены хранятся зашифрованными; в кабинете их можно повторно показать и скопировать. У старого токена может быть доступен только префикс; тогда создайте новый.Copy the token to your application settings. New tokens are stored encrypted and can be revealed and copied again in the cabinet. A legacy token may only expose its prefix; create a replacement in that case.
• Отзывайте ненужные токены там же. После отзыва запросы API с этим токеном отклоняются. Существующие файлы фильтрации используют отдельный секрет и продолжают работу.Revoke unused tokens there. Revoked tokens can no longer authenticate API requests. Existing filtering files use a separate secret and continue working.

Передавайте токен в заголовке каждого запроса:Send the token in the header of every request:

Authorization: Bearer klo_live_1a2b3c4d5e6f7890abcd1234ef567890abcd1234

Права токена (scopes)Token scopes

У токена есть уровень доступа. При создании в кабинете выберите «Доступ на запись», если токену нужны операции изменения; иначе токен будет только для чтения. A token carries an access level. When creating one in the cabinet, tick “write access” if the token needs to modify data; otherwise it is read-only.

Максимум 15 активных токенов на аккаунт. Вместо Authorization поддерживается X-Api-Key, но передавайте только один способ авторизации. Токен в URL не принимается. Для каждого приложения удобно создать отдельный токен с минимальными правами.Up to 15 active tokens per account. X-Api-Key is supported as an alternative to Authorization; use one authentication method per request. URL tokens are not accepted. Use a separate least-privilege token for each application.

Базовый URL и версииBase URL & versioning

https://cabinet.klo-boostclicks.online/api/v1

Все пути в этой документации относительны базового URL. Версия зафиксирована в пути (/api/v1). Ломающие изменения выйдут под новой версией; текущая продолжит работать в переходный период. All paths in this documentation are relative to the base URL. The version is pinned in the path (/api/v1). Breaking changes will ship under a new version; the current one keeps working during the transition.

Лимиты запросовRate limits

Лимит зависит от тарифа и виден в limits.rate_limit_per_min ответа /account:The limit depends on your plan and is exposed as limits.rate_limit_per_min in /account:

Лимит считается отдельно для каждого токена на обслуживающем узле в минутном окне. Ответ после проверки токена содержит заголовки:The limit applies per token on each serving node in a minute window. Responses after token validation include:

При превышении вернётся 429 Too Many Requests с заголовком Retry-After (секунды до сброса). Реализуйте экспоненциальную паузу и повтор.Exceeding it returns 429 Too Many Requests with a Retry-After header (seconds until reset). Implement exponential backoff and retry.

Показатель использования токена в кабинете приблизительный: счётчики находятся в памяти узла, сбрасываются при его перезапуске, сутки считаются по UTC. Он не предназначен для сверки оплаченного трафика.Token usage shown in the cabinet is approximate: counters are node-local, reset after a restart and use UTC days. They are not a billing or traffic reconciliation ledger.

ОшибкиErrors

Ошибки возвращаются с соответствующим кодом HTTP и телом в едином формате:Errors are returned with the appropriate HTTP status and a consistent body:

{
  "error": {
    "code": "invalid_token",
    "message": "API token is invalid or has been revoked."
  }
}

ПагинацияPagination

Списки листаются курсором. Параметр limit задаёт размер страницы; в блоке meta приходит next_cursor - передайте его в параметр cursor следующего запроса. Если has_next=false, страниц больше нет. Collections use cursor pagination. The limit parameter sets the page size; the meta block returns next_cursor - pass it as the cursor parameter of the next request. When has_next=false, there are no more pages.

Курсор непрозрачный: не собирайте и не изменяйте его вручную. Для следующей страницы сохраняйте прежние фильтры и limit. При смене фильтра начинайте без курсора. Изменения данных во время обхода могут сдвигать страницы; сверку проводите за завершённый период, устраняя повторы по event_id.Treat cursors as opaque: do not construct or edit them. Keep the same filters and limit for subsequent pages; restart without a cursor after changing filters. Concurrent data changes may shift pages. Reconcile a completed period and deduplicate by event_id.

{
  "data": [ /* … */ ],
  "meta": {
    "count": 20,
    "total": 57,
    "has_next": true,
    "next_cursor": "eyJvIjoyMH0"
  }
}

Время и полнота данныхTime and data completeness

ts содержит Unix-время в секундах, time, created_at, updated_at и expires_at используют ISO-8601 в UTC. Неизвестная дата может быть null. Даты фильтров и группировка по суткам относятся к часовому поясу статистики кабинета. В графиках используйте meta.timezone, а не часовой пояс браузера.ts is Unix time in seconds; time, created_at, updated_at and expires_at use ISO-8601 UTC. An unknown date may be null. Date filters and daily aggregates use the cabinet statistics timezone. For charts use meta.timezone, not the browser timezone.

История доступна за 7 дней на START и за 45 дней на остальных планах. Точные ограничения возвращает /account. Даты передавайте как YYYY-MM-DD; обе границы включены. Проверяйте фактические meta.from и meta.to: доступный период может быть уже запрошенного.History is available for 7 days on START and 45 days on other plans; /account returns the limits. Use YYYY-MM-DD dates; both boundaries are inclusive. Check effective meta.from and meta.to, as the available period may be narrower than requested.

Аналитика обновляется с задержкой. Проверяйте meta.source и meta.partial, а у счётчиков в объектах кампаний stats_meta. source=clickhouse означает основную аналитику, local_jsonl локальный резерв; partial=true предупреждает о неполной выборке. Не заменяйте последний полный отчёт нулями из неполного ответа: повторите запрос позже.Analytics updates are delayed. Check meta.source and meta.partial, or stats_meta for counters inside campaign objects. source=clickhouse identifies primary analytics; local_jsonl is a local fallback; partial=true warns of incomplete data. Keep the last complete report instead of replacing it with zeros from a partial response, and retry later.

АккаунтAccount

curl https://cabinet.klo-boostclicks.online/api/v1/account \
  -H "Authorization: Bearer klo_live_…"

{
  "data": {
    "key_id": "key-20260101120000-a1b2c3d4",
    "label": "My account",
    "plan": "profit",
    "plan_restricted": false,
    "active": true,
    "expires_at": "2026-09-13T10:00:00+00:00",
    "created_at": "2026-07-13T14:40:28+00:00",
    "domains": ["example.com"],
    "limits": {
      "rate_limit_per_min": 120,
      "history_window_days": 45
    }
  }
}

Сводная статистикаAccount statistics

curl https://cabinet.klo-boostclicks.online/api/v1/stats \
  -H "Authorization: Bearer klo_live_…"

{
  "data": {
    "totals": {
      "today": { "offer": 340, "white": 1290 },
      "total": { "offer": 15803, "white": 64200 }
    },
    "campaigns_count": 3,
    "campaigns": [
      {
        "id": "camp-1a2b3c4d5e6f",
        "name": "Demo LP",
        "is_active": true,
        "today": { "offer": 120, "white": 410 },
        "total": { "offer": 5100, "white": 22010 }
      }
    ]
  }
}

Список кампанийList campaigns

curl "https://cabinet.klo-boostclicks.online/api/v1/campaigns?limit=20" \
  -H "Authorization: Bearer klo_live_…"

{
  "data": [
    {
      "id": "camp-1a2b3c4d5e6f",
      "name": "Demo LP",
      "is_active": true,
      "integration_type": "php_direct",
      "white_url": "main.html",
      "offer_url": "d/index.php",
      "redirect_method": "include",
      "created_at": "2026-07-13T14:40:28+00:00",
      "updated_at": "2026-08-01T09:12:00+00:00",
      "stats": {
        "today": { "offer": 120, "white": 410 },
        "total": { "offer": 5100, "white": 22010 }
      }
    }
  ],
  "meta": { "count": 1, "total": 1, "has_next": false }
}

Одна кампанияGet a campaign

curl https://cabinet.klo-boostclicks.online/api/v1/campaigns/camp-1a2b3c4d5e6f \
  -H "Authorization: Bearer klo_live_…"

{
  "data": {
    "id": "camp-1a2b3c4d5e6f",
    "name": "Demo LP",
    "is_active": true,
    "integration_type": "php_direct",
    "white_url": "main.html",
    "offer_url": "d/index.php",
    "targeting": {
      "countries": ["LT"],
      "devices": ["mobile"],
      "operating_systems": [],
      "browsers": [],
      "browser_languages": ["lt"],
      "block_empty_language": true
    },
    "allowed_ips_count": 0,
    "blocked_ips_count": 4,
    "delayed_start_clicks": 5,
    "stats": { "today": { "offer": 120, "white": 410 }, "total": { "offer": 5100, "white": 22010 } }
  }
}

Статистика кампанииCampaign statistics

{
  "data": {
    "campaign_id": "camp-1a2b3c4d5e6f",
    "today": { "offer": 120, "white": 410 },
    "total": { "offer": 5100, "white": 22010 }
  }
}

История кликовClick history

curl "https://cabinet.klo-boostclicks.online/api/v1/history?action=offer&limit=50" \
  -H "Authorization: Bearer klo_live_…"

{
  "data": [
    {
      "event_id": "0123456789abcdef0123456789abcdef",
      "ts": 1787401200,
      "time": "2026-08-22T12:20:00+00:00",
      "action": "offer",
      "reason": "targeting_match",
      "ip": "5.20.10.4",
      "geo": "LT",
      "site": "example.com",
      "campaign_id": "camp-1a2b3c4d5e6f",
      "browser": "Chrome",
      "device": "mobile",
      "query": "gclid=abc&buyer=demo"
    }
  ],
  "meta": { "count": 50, "total": 1240, "page": 1, "pages": 25, "has_next": true, "next_cursor": "eyJwIjoyfQ" }
}

Живая лентаRealtime feed

curl "https://cabinet.klo-boostclicks.online/api/v1/realtime?after=1787401100" \
  -H "Authorization: Bearer klo_live_…"

{
  "data": [ /* строки как в /history */ ],
  "meta": { "count": 7, "cursor_ts": 1787401242 }
}

v1.2 Клики во времениClicks over time

curl "https://cabinet.klo-boostclicks.online/api/v1/stats/timeseries?granularity=day&from=2026-08-01&to=2026-08-24" \
  -H "Authorization: Bearer klo_live_…"

{
  "data": [
    { "bucket": "2026-08-22", "offer": 3, "white": 1543, "total": 1546, "unique_ips": 150 },
    { "bucket": "2026-08-23", "offer": 0, "white": 529, "total": 529, "unique_ips": 235 }
  ],
  "meta": {
    "granularity": "day", "from": "2026-08-01", "to": "2026-08-24",
    "points": 2, "timezone": "Europe/Moscow",
    "totals": { "offer": 3, "white": 2072, "total": 2075 },
    "source": "clickhouse", "partial": false
  }
}

v1.2 ДоменыDomains

{
  "data": [
    { "host": "example.com",
      "stats": { "total": 7211, "offer": 3550, "white": 3661, "unique_ips": 1204, "pass_rate": 0.4923 } }
  ],
  "meta": { "count": 8, "from": "2026-07-26", "to": "2026-08-24" }
}

{
  "data": {
    "host": "example.com",
    "stats": { "total": 7211, "offer": 3550, "white": 3661, "unique_ips": 1204, "pass_rate": 0.4923 },
    "days": [ { "date": "2026-08-23", "total": 812, "offer": 401, "white": 411 } ],
    "top_white_reasons": [ { "reason": "hosting", "count": 2085 }, { "reason": "bot_ua", "count": 679 } ]
  }
}

v1.2 Файл интеграцииIntegration file

curl --fail --show-error -OJ https://cabinet.klo-boostclicks.online/api/v1/campaigns/camp-1a2b3c4d5e6f/integration \
  -H "Authorization: Bearer klo_live_…"

v1.1 Управление кампаниями (запись)Managing campaigns (write)

Операции записи требуют токен с правом write (см. Права токена). Ограничения по тарифу - те же, что в кабинете. Write operations require a token with the write scope (see Token scopes). Plan limits are the same as in the cabinet.

• php_direct, php_reverse и sdk доступны на всех тарифах, включая START.php_direct, php_reverse and sdk are available on all plans, including START.
• javascript, keitaro, wordpress - тариф PROFIT и выше (иначе 403 plan_upgrade_required).javascript, keitaro, wordpress - PROFIT plan or higher (else 403 plan_upgrade_required).
• cloudflare требует DOMINATION для создания, редактирования, включения, сохранения доступа и развёртывания. Отключение и удаление доступны на любом активном тарифе. API поддерживает создание, изменение, включение, отключение и удаление Cloudflare-кампаний. Чтение статуса своей кампании доступно и на младшем тарифе, чтобы увидеть disabled_plan.cloudflare requires DOMINATION for creation, editing, enabling, saving access and deployment. Disable and delete remain available with any active subscription. The API supports creating, updating, enabling, disabling and deleting Cloudflare campaigns. You can read your campaign status on a lower plan, including disabled_plan.

Допустимые значения таргетингаAllowed targeting values

Значения сверяются точно (регистр нормализуется); неизвестное → 422 validation_error. Пустой список = без ограничения.Values are matched exactly (case is normalized); unknown → 422 validation_error. Empty list = no restriction.

Передавайте JSON-объект с Content-Type: application/json, не массив. Размер тела до 64 КиБ. Boolean-поля передавайте как true/false, списки как массивы строк. Вложенный объект unique_visit описан ниже. Доступны только перечисленные поля; dns_channel доступен только для чтения, собственные DNS-резолверы через API не задаются.Send a JSON object, not an array, with Content-Type: application/json. Maximum body size: 64 KiB. Send booleans as true/false and lists as string arrays. The nested unique_visit object is described below. Only listed fields are writable; dns_channel is read-only, and the API does not accept custom DNS resolvers.

Создать кампаниюCreate a campaign

curl -X POST https://cabinet.klo-boostclicks.online/api/v1/campaigns \
  -H "Authorization: Bearer klo_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Demo LP",
    "integration_type": "php_direct",
    "white_url": "main.html",
    "white_target_mode": "local",
    "offer_url": "https://offer.example.com/lp",
    "countries": ["LT"],
    "devices": ["Mobile"]
  }'

curl -X POST https://cabinet.klo-boostclicks.online/api/v1/campaigns \
  -H "Authorization: Bearer klo_live_…" \
  -H "Idempotency-Key: my-unique-key-42" \
  -H "Content-Type: application/json" \
  -d '{"name":"Demo LP","white_url":"https://example.com/white","offer_url":"https://example.com/offer","is_active":false}'

{ "data": { "id": "camp-9f1c…", "name": "Demo LP", "is_active": true, /* … полный объект кампании … */ } }

Изменить кампаниюUpdate a campaign

curl -X PATCH https://cabinet.klo-boostclicks.online/api/v1/campaigns/camp-9f1c… \
  -H "Authorization: Bearer klo_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Demo LP v2", "countries": ["LT","LV"] }'

{ "data": { "id": "camp-9f1c…", "name": "Demo LP v2", /* … */ } }

Включить / отключитьEnable / disable

curl -X POST https://cabinet.klo-boostclicks.online/api/v1/campaigns/camp-9f1c…/disable \
  -H "Authorization: Bearer klo_live_…"

{ "data": { "id": "camp-9f1c…", "is_active": false, /* … */ } }

Удалить кампаниюDelete a campaign

curl -X DELETE https://cabinet.klo-boostclicks.online/api/v1/campaigns/camp-9f1c… \
  -H "Authorization: Bearer klo_live_…"

{ "data": { "id": "camp-9f1c…", "deleted": true } }

v1.4.0 Сохранённый доступ CloudflareSaved Cloudflare access

Эти маршруты управляют сохранённым доступом к существующему аккаунту Cloudflare. Они не создают аккаунт у Cloudflare. Доступ и кампании принадлежат текущему владельцу Bearer-токена; чужой идентификатор не даёт доступа.These routes manage saved access to an existing Cloudflare account. They do not create an account at Cloudflare. Saved access and campaigns belong to the Bearer token owner; another owner's identifier does not grant access.

Зоны CloudflareCloudflare zones

Статус Cloudflare-кампанииCloudflare campaign status

Развёртывание, повтор и проверка NSDeploy, retry and check nameservers

Все три POST-маршрута требуют scope write и DOMINATION. Существующий фоновый обработчик выполняет развёртывание асинхронно. Запрос API не ждёт установки Worker.All three POST routes require write and DOMINATION. The existing background processor deploys asynchronously. The API request does not wait for Worker installation.

API использует тот же жизненный цикл кампании, что кабинет: изменение целей вызывает обновление, включение - восстановление, отключение и удаление - очистку интеграции. Установка обновления API сама по себе не меняет Worker у клиентов.The API uses the same campaign lifecycle as the cabinet: target changes trigger an update, enabling restores deployment, and disabling or deleting cleans up the integration. Installing the API update alone does not change customer Workers.

Cloudflare: полный пример cURLCloudflare: complete cURL example

Пример для Bash. Все значения ниже - заглушки. Подставьте свой токен с read и write, существующий аккаунт Cloudflare и собственный домен. После каждого шага проверьте HTTP-статус; замените ID на возвращённые API. Требуется DOMINATION.Bash example. All values below are placeholders. Supply your own token with read and write, an existing Cloudflare account and your domain. Check the HTTP status after each step and replace IDs with returned values. Requires DOMINATION.

export KLO_API_TOKEN='KLO_BEARER_TOKEN_PLACEHOLDER'
BASE='https://cabinet.klo-boostclicks.online/api/v1'

# 1. Save access to your existing Cloudflare account.
curl --silent --show-error --fail-with-body --max-time 30 -X POST "$BASE/cloudflare/accounts" \
  -H "Authorization: Bearer $KLO_API_TOKEN" -H 'Content-Type: application/json' \
  -d '{"label":"Example account","email":"owner@example.com","api_key":"GLOBAL_API_KEY_PLACEHOLDER","account_id":"00000000000000000000000000000000"}'

# 2. Use data.id returned above; list zones and note the selected zone ID.
CREDENTIAL_ID='SAVED_ACCESS_ID_PLACEHOLDER'
curl --silent --show-error --fail-with-body --max-time 30 --get "$BASE/cloudflare/accounts/$CREDENTIAL_ID/zones" \
  -H "Authorization: Bearer $KLO_API_TOKEN" \
  --data-urlencode 'domain=example.com' --data-urlencode 'page=1' --data-urlencode 'per_page=20'

# 3. Create a Cloudflare campaign. No Worker is deployed by this request.
curl --silent --show-error --fail-with-body --max-time 30 -X POST "$BASE/campaigns" \
  -H "Authorization: Bearer $KLO_API_TOKEN" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-cf-campaign-001' \
  -d '{"name":"Example Cloudflare","integration_type":"cloudflare","white_url":"https://white.example.com/","offer_url":"https://offer.example.com/","white_target_mode":"url","offer_target_mode":"url","white_method":"302","redirect_method":"302","unique_visit":{"enabled":true,"scope":"campaign","ttl_hours":24,"skip_mobile":false}}'

# 4. Use data.id returned by campaign creation and the zone ID from step 2.
CAMPAIGN_ID='CAMPAIGN_ID_PLACEHOLDER'
curl --silent --show-error --fail-with-body --max-time 30 -X POST "$BASE/campaigns/$CAMPAIGN_ID/cloudflare/deploy" \
  -H "Authorization: Bearer $KLO_API_TOKEN" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-cf-deploy-001' \
  -d "{\"credential_id\":\"$CREDENTIAL_ID\",\"domain\":\"example.com\",\"zone_id\":\"ZONE_ID_PLACEHOLDER\"}"

# 5. Poll status with backoff; 202 means queued, not deployed.
curl --silent --show-error --fail-with-body --max-time 30 "$BASE/campaigns/$CAMPAIGN_ID/cloudflare" \
  -H "Authorization: Bearer $KLO_API_TOKEN"

# 6. After setting the required nameservers at your registrar, check delegation.
curl --silent --show-error --fail-with-body --max-time 30 -X POST "$BASE/campaigns/$CAMPAIGN_ID/cloudflare/check-ns" \
  -H "Authorization: Bearer $KLO_API_TOKEN" -H 'Content-Type: application/json' -d '{}'

# 7. Update one nested setting; other unique_visit fields stay unchanged.
curl --silent --show-error --fail-with-body --max-time 30 -X PATCH "$BASE/campaigns/$CAMPAIGN_ID" \
  -H "Authorization: Bearer $KLO_API_TOKEN" -H 'Content-Type: application/json' \
  -d '{"unique_visit":{"ttl_hours":168}}'

# 8. If deployment needs a retry, use the saved configuration.
curl --silent --show-error --fail-with-body --max-time 30 -X POST "$BASE/campaigns/$CAMPAIGN_ID/cloudflare/retry" \
  -H "Authorization: Bearer $KLO_API_TOKEN" -H 'Content-Type: application/json' -d '{}'

Если домен ещё не делегирован, используйте name_servers из ответа списка зон и повторите проверку после обновления DNS. Для повторного deploy после сетевого сбоя сохраните исходное тело и ключ; для состояния используйте GET.If the domain is not delegated yet, use name_servers from the zone list and check again after DNS updates. Retain the original body and key when retrying deploy after a network failure; use GET to inspect state.

v1.2 OpenAPI-спецификацияOpenAPI specification

Машиночитаемый контракт (OpenAPI 3.1) - по нему генерируются клиенты и импортируется коллекция в Postman/Insomnia:A machine-readable contract (OpenAPI 3.1) - generate clients from it or import it into Postman/Insomnia:

https://cabinet.klo-boostclicks.online/api/openapi.json

Спецификация доступна без токена, описывает маршруты, параметры и схемы ответа. Перед генерацией клиента скачайте актуальную версию. Клиент должен допускать новые поля и учитывать ограничения, описанные выше.The specification is public and describes routes, parameters and response schemas. Download the current version before generating a client. Clients should tolerate new response fields and honor the limits documented above.

# OpenAPI Generator
npx @openapitools/openapi-generator-cli generate \
  -i https://cabinet.klo-boostclicks.online/api/openapi.json \
  -g python -o ./klo-client

ОбъектыObjects

КампанияCampaign

Событие историиHistory event

История измененийChangelog