REST API

API разделено на три логические группы по уровню доступа:

• Ingestion API (collect.trektik.ru) — приём событий от SDK и серверов клиента. Аутентификация SDK-ключом (pk_*).
• API приложения (api.trektik.ru) — дашборды, аналитические запросы, настройки проекта. Аутентификация JWT (сессия пользователя) или секретный ключ (sk_*) с областью доступа для машинного доступа.
• API встраивания — публичный эндпоинт для отображения встроенных виджетов без аутентификации, с JWT-токеном в URL.

Базовые форматы: JSON на вход и выход, timestamps в ISO 8601 (UTC), все числовые идентификаторы целочисленные.

Два типа ключей, две стратегии использования.

SDK-ключи (pk_*)

Публичные ключи для клиентского кода. Прикладываются к каждому запросу заголовком X-Trektik-API-Key. Могут писать только события — никаких чувствительных операций.

Секретные ключи (sk_*)

Серверные ключи. Прикладываются как Authorization: Bearer sk_.... Имеют область доступа:

• query — только чтение аналитических данных
• read — чтение всей конфигурации (дашборды, сегменты, пользователи...)
• write — создание и изменение (но не удаление и не админ-действия)
• admin — всё, включая удаление проектов и ротацию ключей

Создавайте ключи в Настройки → API-ключи с минимально необходимой областью доступа. Ключ показывается один раз при создании — потом в интерфейсе виден только его префикс для идентификации.

JWT (UI)

Для браузерной админки — токены доступа и обновления через POST /v1/auth/login. Токен доступа живёт 15 минут, токен обновления — 30 дней (httpOnly cookie). Для внешнего использования не рекомендуется — берите секретный ключ.

Самый простой сценарий — отправить событие с сервера, минуя браузерный SDK:

curl -X POST https://collect.trektik.ru/v1/track \
  -H "Content-Type: application/json" \
  -H "X-Trektik-API-Key: pk_YOUR_SDK_KEY" \
  -d '{
    "event_name": "purchase_completed",
    "user_id": "user-123",
    "timestamp": "2026-04-22T10:30:00Z",
    "properties": {
      "amount": 4990,
      "currency": "RUB",
      "product_id": "pro-month"
    }
  }'

Пример аналитического запроса (с секретным ключом):

curl -X POST https://api.trektik.ru/v1/query/events \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 1,
    "events": [{"name": "purchase_completed"}],
    "metric": "uniq_users",
    "date_range": {"start": "2026-04-01", "end": "2026-04-30"},
    "interval": "day"
  }'

Полные схемы запросов и ответов — в Swagger UI или в openapi.yaml.

Лимиты зависят от тарифа проекта. Типовые значения:

При превышении возвращается 429 Too Many Requests с заголовком Retry-After (секунды).

Все ошибки возвращают JSON c полем error:

{ "error": "invalid project_id" }

• 400 Bad Request — невалидный JSON / отсутствуют обязательные поля
• 401 Unauthorized — нет или невалидный ключ/токен
• 403 Forbidden — нет доступа к проекту или нет нужной области доступа/роли
• 404 Not Found — объект не существует (или нет прав видеть)
• 409 Conflict — конфликт уникальности (например alias уже существует)
• 429 Too Many Requests — лимит исчерпан, см. Retry-After
• 500 / 503 — проблема на стороне платформы

Платформа шлёт вебхук на ваш URL при срабатывании алерта, завершении экспорта, старте/остановке эксперимента. Настройка в Настройки → Вебхуки.

Общая структура полезной нагрузки:

{
  "event": "alert.fired",
  "timestamp": "2026-04-22T10:30:00Z",
  "project_id": 1,
  "data": {
    "alert_id": 42,
    "alert_name": "Signups dropped",
    "value": 12,
    "threshold": 50,
    "condition": "< threshold"
  }
}

Подпись HMAC-SHA256 приходит в заголовке X-Trektik-Signature, secret — общий для всего проекта, задаётся при создании webhook-а. Валидировать:

import { createHmac } from 'crypto';

function verify(raw, signature, secret) {
  const expected = createHmac('sha256', secret)
    .update(raw)
    .digest('hex');
  return signature === expected;
}

URL для webhook-ов проходит SSRF-валидацию (нельзя указать169.254.169.254, приватные IP-диапазоны, localhost и т.д.).