Справочник API

Базовый URL

Все эндпоинты доступны по адресу {base_url}/api/v1. Для облачной версии {base_url} — это https://perfscale.ru; при self-hosted развёртывании подставьте публичный адрес вашего шлюза.

Полный машиночитаемый контракт доступен в формате OpenAPI: openapi.json. На self-hosted развёртываниях BFF также отдаёт Swagger UI по адресу /swagger-ui/ на своём порту.

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

API поддерживает два типа Bearer-учётных данных, передаваемых в заголовке Authorization:

Authorization: Bearer <token>

Персональные API-токены (psk_…) — рекомендуемый способ обращения к API из скриптов и CI. Токены создаются для конкретного пользователя, поддерживают срок действия и тонкие scope'ы, управляются через /api/v1/api-tokens. Открытое значение токена показывается только один раз при создании. Если scope'ы токена не покрывают операцию, возвращается 403.

Keycloak JWT — короткоживущий access token, выданный Keycloak. Веб-приложение получает его автоматически при входе. При прямых обращениях к API используйте ROPC grant:

curl -X POST {base_url}/realms/perfscale/protocol/openid-connect/token \
  -d "grant_type=password" \
  -d "client_id=perfscale-site" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "username=demo@perfscale.ru" \
  -d "password=demo1234"

Машинные токены — M2M-токены, получаемые из Keycloak по grant'у client_credentials. Они привязывают машину к её workspace и предназначены для агентов (ping машин, приём OTel-метрик), а не для пользовательского доступа к API.

Биллинг

Требуется активная подписка: на платном контуре API отвечает 402 {"code":"PAYMENT_REQUIRED"} на операции /api/v1/* для тенантов без активной подписки. Исключения: auth/me, управление тенантами и платежами, приглашения, подписка.

402 Payment Required

{
  "code": "PAYMENT_REQUIRED",
  "message": "An active paid subscription is required to use this endpoint"
}

Исключения (доступны всегда): GET /api/v1/auth/me, POST /api/v1/contact, POST /api/v1/users/provision, GET /api/v1/tenants, POST /api/v1/tenants/switch, GET /api/v1/tenants/billing-status, GET /api/v1/tenants/payments, POST /api/v1/tenants/subscription/cancel, POST /api/v1/tenants/subscription/resume, а также принятие приглашений.

Интерактивный справочник

Все эндпоинты с параметрами, схемами запросов и ответов и консолью для пробных вызовов:

Ответы с ошибками

Все ответы с ошибками следуют общему формату ApiError:

{
  "code": "NOT_FOUND",
  "message": "Task task_99 does not exist"
}