REST API

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

Базовый URL

https://metriqa.kayaniq.ru

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

API использует два типа аутентификации в зависимости от назначения эндпоинта:

1. Token проекта (для приёма событий)

Эндпоинты /v1/* используют ingest-токен проекта. Токен передаётся в теле запроса или в заголовке X-Metriqa-Token.

2. JWT (для управления и аналитики)

Эндпоинты /api/*, /auth/*, /billing/* используют JWT Bearer-токен. Получить токен можно через POST /auth/login.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Приём событий

POST /v1/batch

Отправить пачку событий. Используется в SDK для буферизации.

Запрос:

{
  "token": "proj_abc123...",
  "events": [
    {
      "event": "signup_complete",
      "distinct_id": "user_42",
      "timestamp": "2026-05-14T12:34:56Z",
      "properties": {
        "plan": "free",
        "utm_source": "google"
      }
    }
  ]
}

Ответ:

{
  "status": "ok",
  "accepted": 1
}

POST /v1/replay/events

Отправить пачку событий записи сессии (rrweb). Лимит — 500 событий за запрос, до 10 МБ.

Аутентификация и пользователи

POST /auth/signup

{
  "email": "email защищён",
  "password": "...",
  "name": "Иван Иванов",
  "org_name": "ООО Ромашка"
}

POST /auth/login

{
  "email": "email защищён",
  "password": "..."
}

Ответ: JWT-токен и refresh-токен в cookie.

POST /auth/refresh

Обновить access-токен по refresh-токену (cookie передаётся автоматически).

POST /auth/logout

Аналитические эндпоинты

Все требуют JWT и возвращают данные по проекту текущего пользователя.

GET /api/events/timeseries

Временной ряд количества событий.

Параметры:

• range — 7d / 30d / 90d
• granularity — hour / day / week
• event — фильтр по конкретному событию (опционально)
• cohort_id — фильтр по когорте (опционально)

GET /api/funnel

Воронка конверсии.

?steps=page_view,signup_start,signup_complete&window=86400&range=30d

GET /api/retention

Когортный retention. Доступен на тарифах «Рост» и «Бизнес».

GET /api/users/active

DAU/WAU/MAU за период.

GET /api/cohorts

Список когорт текущего проекта.

POST /api/cohorts

Создать когорту.

{
  "name": "Active payers",
  "conditions": {
    "logic": "and",
    "conditions": [
      {"type": "did", "event": "payment_success", "count_op": ">=", "count": 1, "range": "30d"},
      {"type": "did", "event": "page_view", "count_op": ">=", "count": 5, "range": "7d"}
    ]
  }
}

Управление проектами

GET /projects

Список проектов организации.

POST /projects

Создать новый проект (только владелец).

Webhooks

GET /api/webhooks

POST /api/webhooks

{
  "url": "https://hooks.slack.com/services/...",
  "events": ["signup_complete", "system.alert_triggered"],
  "secret": "your-hmac-secret"
}

GET /api/webhooks/:id/deliveries

История доставок (включая retry).

Биллинг

GET /billing/status

Текущий тариф, лимиты, дата окончания подписки.

POST /billing/subscribe

{ "plan": "growth" }

Возвращает URL для оплаты через ЮKassa.

POST /billing/cancel

Отменить автопродление. Тариф будет действовать до конца оплаченного периода.

GET /billing/history

История платежей.

Коды ответов

Rate limits

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

Машиночитаемая спецификация API в формате OpenAPI 3.0 доступна по адресу:

https://metriqa.kayaniq.ru/openapi.json