API Reference

REST API контроллера Bcloud Catalyst. Версия v1. База: https://control.catalyst.b-cloud.xyz/v1. Формат обмена — JSON, кодировка UTF-8.

Обзор

Все запросы должны включать заголовок Authorization: Bearer <token>, кроме эндпоинта /auth/token. Ответы всегда содержат request_id для трассировки — указывай его при обращении в поддержку.

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

Два способа: API-ключ (для серверных интеграций) и OAuth2 client credentials (для пользовательских приложений).

bashcurl -H "Authorization: Bearer cat_live_xxxxxxxxxxxxxxxx" \
  https://control.catalyst.b-cloud.xyz/v1/nodes

Токены бывают трёх видов:

Префикс	Тип	TTL
`cat_live_`	Production	до 365 дней (rotatable)
`cat_test_`	Sandbox	30 дней
`cat_ro_`	Read-only	не ограничен

Ошибки

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

json{
  "error": {
    "code": "RULE_NOT_FOUND",
    "message": "Rule with id 'r_8a4f2' does not exist",
    "request_id": "req_01HXK9M3N2P4Q5R6S7T8U9V0W"
  }
}

HTTP	Код	Описание
400	`INVALID_REQUEST`	Некорректный JSON или параметры
401	`UNAUTHORIZED`	Отсутствует/просрочен токен
403	`FORBIDDEN`	Недостаточно прав
404	`*_NOT_FOUND`	Ресурс не существует
409	`CONFLICT`	Конфликт имён / версий
422	`VALIDATION_FAILED`	Политика не проходит валидацию
429	`RATE_LIMITED`	Превышен лимит запросов
500	`INTERNAL`	Внутренняя ошибка (см. request_id)

Rate limits

По умолчанию — 1000 запросов/мин на токен и 100 запросов/мин на IP. Для записи (POST/PUT/PATCH/DELETE) — 300/мин. Заголовки ответа:

httpX-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1731170400

Зоны доступности

Контроллер работает в 5 зонах. Запросы автоматически маршрутизируются в ближайшую по anycast. Принудительно указать зону можно заголовком X-Catalyst-Zone.

eu-central-1 eu-east-1 us-east-1 us-west-1 ap-southeast-1

bashcurl -H "Authorization: Bearer $TOKEN" \
     -H "X-Catalyst-Zone: ap-southeast-1" \
     https://control.catalyst.b-cloud.xyz/v1/nodes

INFO Данные в разных зонах синхронизируются в течение ~200 мс через gossip. При строгой необходимости читать «свежие» данные сразу после записи — передавай X-Catalyst-Consistency: strong (задержка ответа +50–80 мс).

Auth

POST /auth/token

Обмен API-ключа на сессионный токен (для OAuth2 flow).

json{
  "grant_type": "client_credentials",
  "client_id": "pk_live_xxxx",
  "client_secret": "sk_live_xxxx"
}

GET /auth/me

Информация о текущем токене и привязанном аккаунте.

Nodes

GET /nodes

Список всех узлов аккаунта.

Query-параметры: zone, status, limit (≤100), cursor.

json{
  "data": [
    {
      "id": "n_pl1fh",
      "name": "Pl-1_FH",
      "zone": "eu-central-1",
      "status": "online",
      "version": "4.1.0",
      "cpu_pct": 22.4,
      "ram_used_gb": 12.1,
      "rules_active": 47,
      "uptime_sec": 2817042
    }
  ],
  "next_cursor": null
}

GET /nodes/{id}

Детали конкретного узла + последние метрики.

POST /nodes

Создать регистрационный токен для нового узла.

json{
  "name": "Pl-2_MSK",
  "zone": "eu-east-1",
  "labels": { "env": "prod" }
}

INFO Возвращает registration_token, который нужно передать в catalyst init --token=... на самом узле. Токен одноразовый, TTL 30 минут.

DELETE /nodes/{id}

Отключить узел. Сначала выполняется drain, потом узел удаляется.

Rules

GET /rules

Список правил. Query: node, action, enabled.

POST /rules

Создать правило.

json{
  "node": "n_pl1fh",
  "name": "block-known-bad-ips",
  "priority": 5,
  "action": "deny",
  "source": { "feed": "threat-intel:high-confidence" },
  "log": true,
  "enabled": true
}

PATCH /rules/{id}

Частичное обновление. Передавай только меняющиеся поля.

DELETE /rules/{id}

Удалить правило. Нужен ?force=true для правил в активной политике.

Policies

GET /policies/{node}

Текущая применённая политика для узла (YAML в теле ответа).

PUT /policies/{node}

Заменить политику (draft). Не применяется до вызова /apply.

POST /policies/{node}/apply

Скомпилировать и применить. Атомарная операция с rollback при ошибке.

WARN Применение может занять до 5 секунд — BPF-программа собирается под каждое ядро отдельно. Ответ возвращается после подтверждения от узла.

Metrics

GET /metrics/{node}

Агрегированные метрики узла за период.

Query: from, to (ISO-8601), interval (1m, 5m, 1h, 1d).

GET /metrics/{node}/traffic

Time series трафика (in/out в Mbps).

GET /metrics/{node}/events

События фильтра за период. Query: action, rule, limit.

Threat Intelligence

GET /threat-intel/feeds

Список фидов и их состояние (last_sync, entries_count).

POST /threat-intel/feeds/{id}/sync

Принудительная синхронизация фида. Обычно не нужно — фиды обновляются автоматически.

Webhooks

GET /webhooks

Список подписок.

POST /webhooks

Создать webhook. Поддерживаются события: alert.triggered, policy.applied, node.online, node.offline, ti.updated.

json{
  "url": "https://example.com/hooks/catalyst",
  "events": ["alert.triggered", "node.offline"],
  "secret": "whsec_xxxxxxxxxxxx",
  "zones": ["eu-central-1", "eu-east-1"]
}

INFO Каждый запрос подписывается HMAC-SHA256 (заголовок X-Catalyst-Signature). Повторная доставка: 3 попытки с backoff 1s / 10s / 100s.