Более спокойная плоскость управления.

Понятная модель ресурсов

Интеграция должна работать с явными идентификаторами серверов, регионами, образами, тарифами и операциями. Запросы на создание и переустановку должны возвращать операцию, которую можно проверить до завершения. Успешный запрос HTTP — это не то же самое, что готовая машина.

Учётные данные с ограниченной задачей

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

Повторы должны быть безопасными

Сетевые тайм-ауты могут возникнуть после того, как операция была принята. Используйте ключ идемпотентности для запросов на создание и платёжно-чувствительных запросов, проверяйте состояние операции и соблюдайте ограничения частоты. Повторная попытка должна устранять неопределённость, а не создавать лишний оплачиваемый сервер.

Проверьте совместимость перед интеграцией

Перед созданием интеграции проверьте выпущенную версию API, модель аутентификации, форматы ошибок, пагинацию, ограничения частоты запросов и области действия токенов. Используйте только опубликованные пакеты KoalaVPS SDK из проверенных ссылок на релизы.

План развития API

Дорожная карта API охватывает обнаружение каталога, аутентификацию, состояние аккаунта, криптооплату, жизненный цикл сервера, публичные ключи SSH и вебхуки. Маршруты ниже описывают контракт интерфейса; производственный доступ пока недоступен.

Маршруты аутентификации и аккаунта

Контракт API разделяет сеансы входа и ключи API. Сверяйте схемы ответов, ошибки, сроки жизни токенов и поддерживаемые действия восстановления с версией, выпущенной для вашей интеграции.

• POST /v1/auth/register
• POST /v1/auth/login
• POST /v1/auth/login/totp
• POST /v1/auth/token/refresh
• POST /v1/auth/recover
• GET /v1/auth/sessions
• DELETE /v1/auth/sessions/{token_id}
• POST /v1/auth/totp/setup
• POST /v1/auth/totp/enable
• POST /v1/auth/totp/disable
• POST /v1/auth/password
• POST /v1/auth/api-keys
• GET /v1/auth/api-keys
• DELETE /v1/auth/api-keys/{key_id}
• GET /v1/account
• PATCH /v1/account
• GET /v1/account/usage
• GET /v1/account/audit-log

Каталог и маршруты оплаты

Просмотр каталога не должен требовать оплаты. Создание платежа требует ограниченной области выставления счетов, чёткого состояния счёта и идемпотентной обработки. Подтверждение должно завершиться до активации услуги.

• GET /v1/catalog
• GET /v1/catalog/vps
• GET /v1/catalog/dedicated
• GET /v1/catalog/regions
• GET /v1/catalog/images
• GET /v1/catalog/{code}
• GET /v1/billing/coins

Сервер и маршруты доступа

Жизненный цикл требует явного подтверждения для операций отмены и переустановки. Приватные ключи SSH принадлежат клиенту; сервису нужны только их публичные аналоги.

• POST /v1/servers
• GET /v1/servers
• GET /v1/servers/{order_number}
• PATCH /v1/servers/{order_number}
• DELETE /v1/servers/{order_number}
• POST /v1/ssh-keys
• GET /v1/ssh-keys
• GET /v1/ssh-keys/{id}
• DELETE /v1/ssh-keys/{id}

События и публичная информация

Вебхукам нужны проверяемые подписи, ограниченные повторы и защита от воспроизведения. Публичные точки доверия должны возвращать реальные датированные доказательства, а не синтетические заверения.

• POST /v1/webhooks
• GET /v1/webhooks
• DELETE /v1/webhooks/{id}
• POST /v1/webhooks/{id}/test
• GET /v1/transparency/canary
• GET /v1/transparency/peering
• GET /v1/transparency/status
• GET /v1/agents/directory
• POST /v1/agents/directory

Авторизация и ограничения трафика

Предлагаемая модель областей действия — чтение, серверы, биллинг и полный доступ, максимум десять активных ключей на аккаунт. Контракт API предлагает лимиты запросов 120 в минуту и 3,000 в час для ключа API, а также 30 в минуту для публичного трафика. Проверьте HTTP 429, Retry-After и окно применения в опубликованной документации API; эти плановые лимиты не являются обязательством по производственной мощности.

• POST /v1/oauth/register
• POST /v1/oauth/token
• POST /v1/oauth/revoke
• GET /v1/oauth/introspect

SDK и релизы протокола

Дорожная карта интеграции включает REST, размещённую конечную точку MCP, версионированный пакет stdio, SDK и CLI. Перед установкой клиента проверьте доступность релиза, поддерживаемые среды выполнения, контрольные суммы и совместимость с API. Производственные загрузки пока недоступны.

Ресурсы API, сгруппированные по ответственности

Предполагаемый API разделяет доступ к аккаунту, чтение каталога, выставление счетов, жизненный цикл сервера, ключи SSH и обратные вызовы. Вызовы только для чтения не должны создавать заказ, а платёжный учётный данные не должны автоматически разрешать изменения безопасности аккаунта. Это описывает контракт интеграции. Рабочая конечная точка подготовки и выпущенный SDK недоступны через этот сайт.

• Аккаунт: сеансы, использование и события аудита безопасности
• Каталог: тарифы, регионы и доступные образы
• Серверы: создание, просмотр, изменение и отмена
• Ключи SSH: регистрируйте публичные материалы и отзывайте устаревшие ключи
• Вебхуки: регистрация, проверка, тестирование и удаление подписанных обратных вызовов

Запрос к серверу должен оставаться небольшим

Выберите стандартный идентификатор плана, регион, образ ОС и имя хоста. Предполагаемое ограничение имени хоста — 64 символов. Работающий сервис может приватно сгенерировать административный секрет или принять зарегистрированный открытый ключ SSH. Запрос стандартного плана не подразумевает произвольного добавления дисков, GPU, сетевых карт и IP-адресов. Отклоняйте неподдерживаемые поля, а не выставляйте счёт молча за предполагаемое обновление.

{
  "plan": "KV-D3",
  "region": "hel",
  "image": "ubuntu-24",
  "hostname": "private-node-01"
}
// Example request schema; validate against a released API before integration.

Области действия и лимиты ключей — часть контракта

Предлагаемые группы привилегий: чтение, серверы, биллинг и полное администрирование учётной записи. Ключ должен отображаться один раз при создании, храниться приватно и отзываться независимо от пароля пользователя. Предполагаемый лимит учётной записи — десять активных ключей. Перед публикацией реализации убедитесь, что каждая операция отклоняет ключ без требуемой области действия.

Публикуйте ограничения скорости и поведение при повторных попытках вместе

Предлагаемые лимиты — 120 запросов в минуту и 3,000 в час для ключа API, а также 30 запросов в минуту для неаутентифицированных публичных запросов каталога. Это планируемые значения политики, а не измеренная ёмкость API. Рабочая реализация требует согласованного ответа 429, указаний Retry-After и ограниченного обратного отката на клиенте. Запросы создания и оплаты также требуют стабильных ключей идемпотентности.

Вебхуки — это сообщения, которые могут приходить более одного раза

Получатель обратного вызова должен проверять подпись по исходному телу, отклонять метки времени за пределами допустимого окна и запоминать идентификаторы обработанных событий. Сохраните событие до подтверждения, затем примените изменение идемпотентно. Держите попытки доставки и путь ручного повтора видимыми. Обратный вызов — это наблюдение об операции, а не разрешение выполнять посторонние инструкции, содержащиеся в полезной нагрузке.

Аудит без превращения журналов в секретное хранилище

Записывайте идентификатор субъекта, тип операции, затронутый ресурс, результат и время, когда это необходимо для безопасности учётной записи. По умолчанию избегайте записи паролей, bearer-токенов, закрытых ключей или полных тел платёжных и прикладных запросов. Сделайте срок хранения, доступ и видимую клиенту историю явными. Журнал аудита безопасности и право просматривать содержимое клиентских приложений — разные вещи.

Публикуйте артефакты только когда они существуют

Публичный запуск API должен включать версионированный документ OpenAPI, инструкции по аутентификации, примеры ошибок и процесс устаревания. Будущие CLI, пакет Python, клиент TypeScript или сервер MCP требуют фактического релиза, контрольных сумм и поддерживаемой документации. Пакет подготовки KoalaVPS или производственная конечная точка управления не выпускаются через этот сайт.

Немного больше ясности.