Документация API

Planeon предоставляет REST API наряду с веб-консолью; сама веб-консоль — лишь один из его клиентов. Источник истины для формы каждого запроса и ответа — документ OpenAPI 3.1.

Документ OpenAPI

API отдаёт собственный документ OpenAPI по адресу:

GET /openapi.yaml

Интерактивная документация

Просматриваемая интерактивная документация API (Scalar) обслуживается самим API-сервисом по адресу:

GET /docs

Используйте её, чтобы изучить каждый эндпоинт и схему и опробовать запросы прямо на вашем инстансе — она всегда отражает именно тот контракт, который обслуживает запущенная у вас версия.

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

Вызовы API аутентифицируются так же, как веб-консоль: OIDC access-токеном от вашего провайдера идентификации, передаваемым как bearer-токен:

Authorization: Bearer <access-token>

Получите токен у вашего провайдера идентификации так же, как это делает веб-консоль, — через поток OAuth2/OIDC с issuer и клиентом, настроенными для вашего инстанса Planeon (см. Провайдеры идентификации). Planeon проверяет issuer, audience, подпись и срок действия токена при каждом запросе; собственных API-ключей или паролей платформа не выдаёт и не хранит.

GET /openapi.yaml, GET /docs и эндпоинты health/readiness (/healthz, /readyz) публичны и не требуют токена.

Права доступа

Каждая операция API подчиняется той же модели прав, что и веб-консоль — отдельного уровня доступа только для API не существует. Операции чтения требуют права :read для соответствующего ресурса (например, pools:read), а операции создания, изменения или удаления — права :manage (pools:manage); platform:admin переопределяет любую проверку. Полный список прав и то, как выдать их пользователю или группе, см. в разделе Управление доступом → Встроенные права.