API 参考
使用 API 操作并解释其结果
阅读可用的端点、幂等性规则、排队操作响应以及操作跟踪的当前限制。
开始之前
- 有效会话，以及对于受保护的更改，其CSRF令牌。
- 从当前目录或经过身份验证的 API 响应中获取的标识符。
- 每个订单、提现或硬件操作的唯一幂等键。
更改前先阅读账户
使用读取端点确认账户、余额和目标资源。GET /api/v1/me 返回用户名、balanceUsd 和会话的 csrfToken。资源标识符是账户特定的；请使用当前账户返回的服务器或网络标识符，而不是从其他环境复制值。
当前的 API 是一个紧凑的账户接口，而不是完整的异步作业平台。在您自己的记录中保存成功写入的引用。没有端点可以列出每个订单、检查特定排队操作或检索提现的最新审核状态。
| 读取端点 | 返回的数据 |
|---|---|
| GET /api/v1/ledger | 最新的100分类账条目，最新的在前；无分页契约。 |
| GET /api/v1/servers | 未终止的服务器、状态、区域、paidThrough、graceUntil 和 autoRenew。 |
| GET /api/v1/network | 分配的地址、前缀长度、PTR 值和相关服务器标识符。 |
| GET /api/health | 基本服务和目录计数；不保证账户或物理服务器健康。 |
使用匹配的更改端点
支持的服务器操作包括重启、power_off、重装、mount_iso、KVM 和 rotate_root_password。自定义 ISO URL 必须使用不带嵌入凭据的公共 HTTPS。订单周期为每周或每月，分别代表七天或三十天。价格、折扣、资金和容量由服务检查；不要将客户端计算的价格作为权威。
| 端点 | 请求字段与结果 |
|---|---|
| POST /api/v1/orders | configId、regionId、osId、term、quantity；可选 sshPublicKey。返回订单 ID 和 ACCEPTED。 |
| POST /api/v1/deposit-addresses | 资产。返回地址、资产、网络、所需确认数和模式，或结算不可用错误。 |
| POST /api/v1/withdrawals | 资产、目的地、美元。返回 id 和 PENDING_REVIEW；余额被保留。 |
| POST /api/v1/servers/{id}/actions | 操作；mount_iso 的 isoUrl。返回操作 ID 和 QUEUED。 |
| PUT /api/v1/servers/{id}/ddos | 模式：BASELINE 或 ADVANCED。返回 QUEUED 或 UNCHANGED 以及 quoteRequired。 |
| PUT /api/v1/network/{id}/rdns | ptr，或空值以清除它。返回存储的 PTR 值。 |
使重试有意识
订单、提现、服务器操作和 DDoS 请求需要 Idempotency-Key。使用 8–100 字母、数字、连字符或下划线，并为每个不同的预期操作分配一个新密钥。在发送之前保留原始密钥、资源和负载，以便调查不确定的响应。
订单可以为相同的密钥和规范化请求重放现有结果；更改订单详情会产生冲突。服务器操作重放在兼容时返回现有操作。保持操作密钥在账户中的所有服务器上唯一。提现如果已记录则报告冲突，而不是将原始请求作为成功返回。
POST /api/v1/servers/{serverId}/actions HTTP/1.1
Content-Type: application/json
x-csrf-token: <current-session-token>
Idempotency-Key: <unique-operation-key>
Cookie: <current-session-cookies>
{"action":"reboot"}区分验收和完成
202 QUEUED 响应确认硬件请求已记录。它不包含可用的 KVM URL、替换的 root 密码或机器已重启的证明。同样，ACCEPTED 记录订单进入配置阶段；PENDING_REVIEW 记录提现等待操作员审核。在询问执行情况时保留返回的标识符。
此版本中没有操作状态轮询路由。在相关情况下重新读取服务器或网络数据，并获取操作员对物理效果的确认。仅存储的 PTR 或 DDoS 偏好不是公共 DNS 或实时网络保护的测量。
在不重复工作的情况下响应故障
- 400 验证错误：在重新提交前更正文档中指定的字段。
- 401 或 403：在重试之前修复会话认证或 CSRF 验证。
- 404：验证资源标识符属于已登录的账户。
- 409：检查错误代码；余额不足、容量耗尽和幂等性冲突需要不同的响应。
- 502 或 503 存款：未返回可用的新地址；不要发起转账。
- 超时或不可读的响应：检查可用的账户记录并保留原始请求详情。不要盲目创建新的操作密钥。