更从容的控制平面。

清晰的资源模型

集成应使用明确的服务器标识符、区域、镜像、方案和操作。创建和重装请求应返回一个可检查至完成的操作。HTTP 请求成功并不等同于机器已就绪。

职责有限的凭据

API 令牌应可独立撤销，并限制在所需的最小资源和操作范围内。将它们存储在密钥管理器或受保护的环境中。绝不要仅仅为了避免编写小型后端而将令牌发送到浏览器。

重试必须安全

操作被接受后可能发生网络超时。对创建和支付敏感请求使用幂等键，检查操作状态并遵守速率限制。重试应消除不确定性，而不是创建额外计费服务器。

集成前检查兼容性

在构建集成之前，请检查已发布的 API 版本、身份验证模型、错误格式、分页、速率限制和令牌范围。仅使用来自已验证发布链接的已发布 KoalaVPS SDK 包。

API 路线图

API 路线图涵盖目录发现、身份验证、账户状态、加密计费、服务器生命周期、公共 SSH 密钥和 webhook。以下路由描述接口契约；生产访问尚不可用。

身份验证和账户路由

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}

事件与公开信息

Webhook 需要可验证的签名、有界重试和重放防护。公开信任端点应返回真实的带日期证据，而不是合成保证。

• 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 合同提议 API 密钥每分钟 120 次、每小时 3,000 次的请求预算，公共流量为每分钟 30 次。请查阅已发布的 API 文档中的 HTTP 429、Retry-After 和执行窗口；这些路线图预算不构成生产容量承诺。

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

SDK 和协议版本

集成路线图包括 REST、托管的 MCP 端点、带版本号的 stdio 包、SDKs 和 CLI。安装客户端前，请检查发布可用性、受支持的运行时、校验和以及 API 兼容性。生产下载尚不可用。

API 资源，按职责分组

预期的 API 将账户访问、目录读取、账单、服务器生命周期、SSH 密钥和回调分开。只读调用不应创建订单，账单凭据不应自动授权账户安全变更。这描述的是集成契约。本网站不提供生产环境开通端点和已发布的 SDK。

• 账户：会话、使用情况与安全审计事件
• 目录：套餐、区域和可用镜像
• 服务器：创建、查看、变更与取消
• SSH 密钥：注册公开材料并撤销过时密钥
• Webhook：注册、检查、测试和移除签名回调

服务器请求应保持精简

选择标准套餐标识符、区域、操作系统镜像和主机名。预期主机名限制为 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.

权限范围和密钥限制是约定的一部分

拟议的权限组为读取、服务器、账单和完整账户管理。密钥应在创建时显示一次，私下存储，并可独立于用户密码撤销。拟定的账户上限为十个活跃密钥。在发布实现前，请验证每项操作都会拒绝缺少所需范围的密钥。

同时发布速率限制和重试行为

建议的限制为：API 密钥每分钟 120 次请求、每小时 3,000 次请求；未认证的公开目录请求每分钟 30 次请求。这些是计划中的策略值，并非实测的 API 容量。实际实现需要一致的 429 响应、Retry-After 指引以及有上限的客户端退避。创建和支付请求还需要稳定的幂等键。

Webhook 是可能多次到达的消息

回调接收方应基于原始请求体验证签名，拒绝超出允许时间窗口的时间戳，并记录已处理的事件标识符。在确认前先持久化事件，然后以幂等方式应用变更。保持投递尝试和手动重放路径可见。回调是对某次操作的观察，而非执行载荷中无关指令的许可。

审计而不将日志变成秘密存储

在账户安全需要时，记录操作者标识符、操作类型、受影响的资源、结果和时间。默认避免记录密码、持有者令牌、私钥或完整的支付和应用请求正文。明确保留期限、访问权限和客户可见历史。安全审计追踪与检查客户应用内容的权利是两回事。

仅在产物存在时才发布

公开的 API 发布应包含带版本的 OpenAPI 文档、认证说明、错误示例和弃用流程。未来的 CLI、Python 包、TypeScript 客户端或 MCP 服务器需要实际的发布版本、校验和以及持续维护的文档。KoalaVPS 开通包或生产管理端点不会通过本站发布。

多一点清晰。